System Requirements Document for gamma-start

1. Introduction

gamma-start is a simple calculator delivered as a single-page design. The product exists so that anyone who needs quick everyday arithmetic can open one page, enter numbers and operators, read the running expression and the result, and clear the calculation to start again — without leaving the page, without an account, and without navigating anywhere else.

The audience is broad and non-technical: a person who wants a key to respond instantly and a number to read perfectly. The design intent is "charming clarity" — a calculator built like a set of perfect little icons, in the spirit of Susan Kare: chunky-outlined keys on a tidy grid, a monospaced pixel display, crisp pixel accents, and no decorative flourish that gets in the way of the numbers.

The single hard constraint from the requester is that the design must be a simple single page. Everything in this document is scoped to that one page.

2. System Overview

gamma-start is a browser-delivered, single-page calculator. There is exactly one page in the product: Calculator. It is anonymously reachable, requires no identity, and holds no durable per-user state. A visitor arrives, performs arithmetic, and leaves; nothing about the visit needs to be remembered.

Actors

• Calculator User (human, active) — the person performing arithmetic on the page.
• Frontend application (system) — the React application that renders the page, holds the in-page calculation state, and responds to key presses.
• Shared backend (system) — the provisioned FastAPI process. It is available infrastructure for application APIs and domain modules; the accepted calculator behavior does not require it to hold calculator state, and no calculator API is specified by the source.
• Database (system) — the provisioned MariaDB instance. It is available infrastructure; the accepted calculator behavior creates no application-owned persistent data, so no domain entities, tables, or authentication are derived from its presence.

Accepted behavior

The page presents a display and a key grid. The user enters digits and operators, sees the running expression and the result, and clears the calculation. That is the whole product.

Delivery and ownership

The calculator is first-party custom UI owned by the application, delivered as one page. There is no provider-owned surface, no external destination, and no headless delivery. Access is anonymous: no sign-in, no account, no session continuity is required or introduced.

Narrow exclusions

No additional pages, no navigation between destinations, no accounts or profiles, no saved history, no sharing or export, no scientific or programmer modes, and no server-side calculation service are part of the current product.

Removed from scope

• Multi-page navigation or additional destinations beyond the single calculator page.
• User accounts, sign-in, profiles, and saved calculation history.
• Scientific, programmer, or unit-conversion calculator modes.
• Sharing, export, or persistence of calculations.

2a. Product Interpretation and Delivery Boundary

The requester asked for a simple single-page design of a calculator. That is read literally: one page, one calculator, no surrounding application. The page is the product.

The page is public and anonymous. A visitor needs no identity to use it, and the product deliberately does not establish one — there is no durable actor-specific state to own, resume, or protect, so introducing sign-in would add a capability the source never asked for. The calculator's state lives in the page for the duration of the visit and is discarded when the visitor leaves or clears it.

The provisioned backend and database are infrastructure that exists in the project scaffold. They do not, by themselves, create product requirements: no calculator API, no stored calculations, and no authentication are specified. If a future requirement needs server-side behavior, it belongs in the existing shared backend rather than a new service.

Everything described here is current. No future-horizon requirements were stated by the requester.

2c. Page Content and Component Coverage

The page contract is exact and contains one page. The page is represented once below.

Calculator

Purpose and information/state

The single page of the product. It presents a calculator as a crafted object on a warm paper field and lets the Calculator User perform arithmetic in place.

State held by the page:

• Current entry — the digits the user is typing, shown as the active number.
• Running expression — the sequence of entered operands and operators, shown right-aligned in small uppercase mono above the result.
• Result — the computed value, shown in oversized VT323 pixel numerals below the expression, right-aligned like an LCD.
• Active operator — which operator key is currently held, shown with a solid accent fill.
• Error state — shown in the result line when an operation cannot be evaluated (for example division by zero).

Primary actions

• Press a digit key (0–9) to append it to the current entry.
• Press a decimal point key to begin or extend a fractional entry.
• Press an operator key (÷, ×, −, +) to commit the current entry and select the operation.
• Press the full-width equals key to evaluate the expression and show the result.
• Press AC to clear the entire calculation and return to the empty starting state.
• Press ± to toggle the sign of the current entry.
• Press % to apply percent to the current entry.

Supporting actions and content

• A compact pixel wordmark at the top of the panel, with a tiny 16×16 pixel calculator glyph beside it.
• A one-line descriptor under the wordmark.
• A short two-line caption below the panel explaining how to use it.
• A quiet decorative column of 4px pixel squares in the paper margin.

Domain entities

• Expression — the ordered operands and operators entered since the last clear.
• Entry — the number currently being typed.
• Result — the evaluated value of the expression.

These are in-page values only; none is persisted.

Component responsibilities

• Calculator panel — the 2px ink-framed, pixel-corner-notched container with a hard 3px offset edge, holding the display and keypad. Max width 420px, centred on the paper field.
• Display band — the ink display area at the top of the panel, separated from the keypad by a dashed 1px rule; renders the running expression above and the result below, both right-aligned with tabular numerals.
• Key grid — the 4×5 grid of flat bordered key tiles: AC, ±, %, ÷ on row one; digits and operators in familiar phone-pad order; a full-width equals key in vermilion accent.
• Key tile — a flat square with a 2px ink border and a 3px hard offset shadow that snaps to zero on press.
• Wordmark and glyph — the pixel wordmark and the 16×16 calculator mark.
• Caption — the two-line usage note below the panel.

States

• Loading — not applicable; the page renders its full calculator immediately with no data fetch.
• Empty — the starting state: display shows a zero result and an empty expression; all keys are available.
• Success — the expression and result are shown; the result line performs a single 120ms blink-then-settle when it updates.
• Error — an unevaluable operation shows an error indication in the result line; the user recovers by pressing AC to clear and begin again.
• Recovery — AC always returns the page to the empty state from any state, including error.

3. Functional Requirements

FR-1 — Open the calculator page As a Calculator User, I should open the single calculator page and immediately see a working calculator, so that I can start arithmetic without any setup.

• Provenance: explicit (single-page calculator).
• Lifecycle: trigger — visiting the page; observable result — the calculator panel with display and key grid is rendered; access — anonymous, no identity required; failure/recovery — not applicable; continuation — the user begins entering digits.
• Acceptance: the page loads directly into the empty calculator state with all keys available.

FR-2 — Enter digits As a Calculator User, I should press digit keys to build a number, so that I can enter the operands of my calculation.

• Provenance: explicit (calculator).
• Lifecycle: input — digit key press; observable result — the digit appears in the current entry and the display updates; failure/recovery — none; continuation — the user continues entering digits or selects an operator.
• Acceptance: each digit press appends exactly one digit to the current entry, and digits align in tabular cells without shifting the layout.

FR-3 — Enter a decimal value As a Calculator User, I should press the decimal point key to enter fractional numbers, so that I can calculate with non-integers.

• Provenance: required_inference (indispensable to a usable calculator).
• Lifecycle: input — decimal key press; observable result — a decimal point is placed in the current entry; failure/recovery — a second decimal point in the same entry is not added; continuation — the user continues entering digits.
• Acceptance: the current entry accepts one decimal point.

FR-4 — Select an operator As a Calculator User, I should press an operator key to choose the operation, so that the calculator knows what to do with my numbers.

• Provenance: explicit (calculator).
• Lifecycle: input — operator key press; observable result — the current entry is committed to the running expression, the operator appears in the expression line, and the operator key holds a solid accent fill; failure/recovery — none; continuation — the user enters the next operand.
• Acceptance: the selected operator is visibly active and appears in the running expression.

FR-5 — Evaluate the expression As a Calculator User, I should press the equals key to compute the result, so that I get the answer to my calculation.

• Provenance: explicit (calculator).
• Lifecycle: input — equals key press; observable result — the result line updates with the computed value and performs a single 120ms blink-then-settle; failure/recovery — an unevaluable expression shows an error in the result line; continuation — the user may continue calculating from the result or clear.
• Acceptance: the displayed result is the correct evaluation of the entered expression.

FR-6 — Clear the calculation As a Calculator User, I should press AC to clear everything, so that I can start a fresh calculation.

• Provenance: explicit (clear the calculation).
• Lifecycle: input — AC key press; observable result — the expression and result return to the empty starting state; failure/recovery — AC also recovers from an error state; continuation — the user begins a new calculation.
• Acceptance: after AC, the display shows the empty starting state and no prior entry remains.

FR-7 — Toggle sign As a Calculator User, I should press ± to change the sign of the current entry, so that I can calculate with negative numbers.

• Provenance: required_inference (indispensable to a usable calculator; key specified in the key grid).
• Lifecycle: input — ± key press; observable result — the current entry's sign flips and the display updates; failure/recovery — none; continuation — the user continues the calculation.
• Acceptance: pressing ± twice returns the entry to its original sign.

FR-8 — Apply percent As a Calculator User, I should press % to apply percent to the current entry, so that I can work with percentages.

• Provenance: required_inference (indispensable to a usable calculator; key specified in the key grid).
• Lifecycle: input — % key press; observable result — the current entry is converted to its percent value and the display updates; failure/recovery — none; continuation — the user continues the calculation.
• Acceptance: the current entry is divided by one hundred and shown in the display.

FR-9 — Read the running expression and result As a Calculator User, I should see the running expression above and the result below in the display, so that I can follow what I have entered and what it evaluates to.

• Provenance: explicit (sees the expression and result).
• Lifecycle: trigger — any entry or evaluation; observable result — the expression line shows the entered operands and operators in small uppercase mono, and the result line shows the value in oversized pixel numerals, both right-aligned; failure/recovery — error text replaces the result; continuation — the user keeps calculating.
• Acceptance: both lines are legible and stay inside the display band at 375px, 768px, and 1280px.

FR-10 — Press feedback on keys As a Calculator User, I should feel each key respond the instant I press it, so that the calculator feels trustworthy and immediate.

• Provenance: explicit (creative direction: keys depress 2px with their offset shadow snapping to zero in 80ms and release instantly).
• Lifecycle: input — key press; observable result — the key depresses 2px and its offset shadow snaps to zero, releasing instantly; failure/recovery — with prefers-reduced-motion the press state becomes a colour change only; continuation — the entry updates.
• Acceptance: no motion delays a keypress or a result.

4. User Personas

Calculator User

Product context. The Calculator User is anyone who needs quick everyday arithmetic — a broad, non-technical audience. They arrive at the page with a number problem in mind and no patience for setup, sign-in, or navigation. The page is the whole product to them.

Primary goal. Get an accurate result to a simple calculation without leaving the page.

Distinct accepted responsibilities. The Calculator User is the only human actor. They enter numbers and operators, read the running expression and result, and clear or correct input to start a new calculation. They are both the initiator and the sole beneficiary of every state change on the page — there is no counterparty, no handoff, and no commitment to another participant.

Relevant inputs and decisions. Which digits to enter, which operator to select, when to press equals, and when to clear. They decide when a calculation is finished and whether to continue from the result or start fresh.

Interactions with other participants. None. The Calculator User interacts only with the page itself; the frontend application responds to their presses, and no other human participant is affected by the outcome.

Observable success. The result line shows the correct answer, the expression above matches what they entered, and they never had to leave the page to get it.

5. Core User Flows

Flow 1 — Perform a basic calculation

1. The Calculator User opens the single calculator page. The page renders immediately in the empty state: the display shows a zero result and an empty expression, and all keys are available. No identity is requested.
2. The user presses digit keys. Each digit appears in the current entry, right-aligned in tabular cells, and the display updates.
3. The user presses an operator key (for example +). The current entry is committed to the running expression, the operator appears in the expression line, and the operator key holds a solid accent fill.
4. The user presses digit keys for the second operand. The current entry updates in the display.
5. The user presses the full-width equals key. The result line updates with the computed value and performs a single 120ms blink-then-settle. The expression remains visible above.
6. Continuation: the user may press an operator to continue calculating from the result, or press AC to clear and start again.

Failure/recovery: if the expression cannot be evaluated (for example division by zero), the result line shows an error. The user presses AC, the page returns to the empty state, and they begin a new calculation.

Flow 2 — Correct or restart a calculation

1. The Calculator User is mid-calculation with an expression and a result on screen.
2. The user presses AC. The expression and result return to the empty starting state; no prior entry remains.
3. The user begins a new calculation by pressing digit keys.
4. Continuation: the new calculation proceeds as in Flow 1.

Failure/recovery: AC is available from every state, including the error state, and always returns the page to the empty state.

Flow 3 — Calculate with a negative or fractional value

1. The Calculator User enters a number using digit keys.
2. The user presses the decimal point key to enter a fractional value, or presses ± to flip the sign of the current entry. The display updates to show the changed entry.
3. The user presses an operator key and enters the second operand.
4. The user presses equals. The result line updates with the computed value.
5. Continuation: the user continues or clears as in Flow 1.

Flow 4 — Apply a percentage

1. The Calculator User enters a number using digit keys.
2. The user presses %. The current entry is converted to its percent value and the display updates.
3. The user presses an operator key and enters the second operand.
4. The user presses equals. The result line updates with the computed value.
5. Continuation: the user continues or clears as in Flow 1.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. The muse is Susan Kare, and the headline idea is "Charming clarity: a calculator built like a set of perfect little icons."

Colour tokens (light mode)

Proportion: ~70% paper, 20% ink, 8% surface, 2% accent.

Typography

• Headings and display: VT323, uppercase, wide tracking, never below 20px so glyphs stay crisp.
• Keys and labels: IBM Plex Mono medium, with tabular numerals so digits align in the display.
• Body: IBM Plex Mono.
• Scale: 1.25 modular on a 4px baseline. Display numerals clamp(40px, 9vw, 88px) in VT323; wordmark clamp(20px, 3vw, 28px); key glyphs clamp(18px, 2.4vw, 26px); labels 12px uppercase with 0.14em tracking; body 15px/1.6.

Shape language

Hard 90° corners everywhere — no border radius on keys, panel, or display. Keys are flat squares with a 2px ink border and a 3px hard offset shadow (no blur) that disappears on press. A 2px ink rule frames the whole calculator; a dashed 1px rule separates the display from the keypad. Pixel-corner notches — a single 4px square cut from two opposite corners of the panel — give the frame a hand-built icon feel.

Spacing rhythm

4px baseline. Single column, centred on a max-width 420px calculator panel with a wide paper margin around it. At 375px the panel goes edge to edge with 16px gutters and keys stay ≥48px tall; at 768px and 1280px it stays a compact object floating in generous paper space.

Imagery style

The interface is the imagery. One small hand-drawn pixel motif — a tiny 16×16 calculator glyph — sits beside the wordmark; a few 4px pixel squares act as quiet decoration in the paper margin. No photography, no illustration beyond pictograms.

Avoid

Rounded corners, pill buttons, soft blurred shadows; Bootstrap-blue or indigo accents on white; gradient blobs, glass panels, floating hover-lift cards; skeuomorphic gloss, bevels, or LCD green-on-black retro clichés; photography or character illustration; Inter, Roboto, Poppins, or system-ui type; decorative motion that delays a keypress or a result.

7. Signature Design Concept

The first screen is the calculator itself as a crafted object — not a marketing hero.

A warm paper field (#F2EEE6) fills the viewport. A single off-white panel (#FFFDF7) with a 2px ink frame sits slightly left of centre at 1280px (centred at 375 and 768), its ink display band at the top showing a large VT323 expression and a vermilion-green result. The panel is the dominant element at roughly 420×640px, casting no soft shadow — only its hard 3px offset edge. Above it, a compact pixel wordmark; to its right in the empty paper, a vertical stack of three tiny pixel glyphs as a quiet decorative column. No headline over the fold, no blue button, no gradient.

The signature moves that make it recognisable:

• A 2px ink-framed calculator panel with pixel-corner notches and a hard 3px offset edge — a physical object on paper, not a floating card.
• A VT323 pixel display with the running expression in small uppercase mono above and the result in oversized pixel numerals below, aligned right like a real LCD.
• Keys as flat bordered tiles whose offset shadow snaps to zero on press, with the equals key as a full-width vermilion block.
• A tiny 16×16 pixel calculator glyph as the only mark, with a decorative column of 4px pixel squares in the paper margin.
• Tabular numerals in IBM Plex Mono throughout so every digit sits in its own cell and never shifts the layout.

This concept recomposes only accepted content, states, and controls: the display, the key grid, the wordmark, the caption, and the press feedback.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject: the calculator panel itself — the 2px ink-framed object with its display band and key grid, sitting on the warm paper field.
• Input → transformation → outcome thesis: a key press depresses the key 2px and snaps its offset shadow to zero in 80ms, releasing instantly; the display's result line performs a single 120ms blink-then-settle when it updates; the active operator key holds a solid accent fill. The outcome is an immediate, legible number — never a delayed one.
• Motion vocabulary: frame-by-frame, no easing theatrics. No hover lifts, no fades, no gradients. Press states are hard and instant.
• Composed first frame: the paper field fills the viewport; the panel sits slightly left of centre at 1280px (centred at 375/768); the display shows the empty starting state with a zero result; the wordmark and pixel glyph sit above; the decorative pixel column sits in the right margin.
• Reduced-motion state: with prefers-reduced-motion, the press state becomes a colour change only; the result line does not blink; the layout is unchanged and fully usable.

9. Non-Functional Requirements

NFR-1 — Single page (explicit). The product is delivered as exactly one page. No additional destinations, routes, or navigation are introduced. Rationale: the requester's hard constraint.

NFR-2 — Simplicity (explicit). The design must be a simple single-page calculator. No feature beyond entering numbers and operators, reading the expression and result, and clearing is added. Rationale: the requester's hard constraint.

NFR-3 — Anonymous access (required_inference). The page requires no identity, sign-in, or session. No durable actor-specific state exists to protect, so no authentication is introduced. Rationale: the calculator's state is ephemeral and per-visit.

NFR-4 — Immediate response (explicit, from creative direction). No motion delays a keypress or a result. Key press feedback completes in 80ms; the result blink-then-settle completes in 120ms.

NFR-5 — Legibility at every viewport (explicit, from creative direction). Readable text and controls stay whole at 375px, 768px, and 1280px: the wordmark, labels, numbers, and keys stay entirely inside the viewport and their container, wrapping or scaling with clamp(...) to fit. No other element covers any part of them.

NFR-6 — Accessible reduced motion (explicit, from creative direction). With prefers-reduced-motion, the press state becomes a colour change only and the result line does not blink; the page remains fully usable.

NFR-7 — No persistence (required_inference). The calculator holds no durable state. The provisioned database is not used for calculator data, and no domain entities or authentication are derived from its presence.

10. Tech Stack

• Frontend: React application UI — the single calculator page, rendered client-side.
• Backend: shared FastAPI process for application APIs and domain modules. The accepted calculator behavior requires no calculator API; the backend remains available infrastructure and is the correct home for any future server-side behavior rather than a new service.
• Database: MariaDB for application-owned persistent data. No calculator data is persisted, so no schema is derived from the current requirements.
• Containerization: Docker / docker-compose, with the provisioned services backend, database, and frontend.

Presentation defaults [Default — not specified by user]: the frontend is a standard React single-page build served as static assets; no additional infrastructure (queue worker, cache, separate ingress) is needed for the accepted workflows.

11. Assumptions and Constraints

• A-1 (explicit constraint). The design must be a single page. This is binding and is not relaxed anywhere in this document.
• A-2 (explicit constraint). The product is a simple calculator; no adjacent calculator capabilities (history, memory registers, scientific functions, unit conversion) are added.
• A-3 (required_inference). The calculator's state is ephemeral and per-visit; no identity, account, or persistence is introduced.
• A-4 (required_inference). The decimal point, ±, and % keys are part of the specified key grid and are treated as indispensable to a usable calculator.
• A-5 (infrastructure). The provisioned backend and database exist in the scaffold but carry no calculator requirements; they do not justify domain entities or authentication.
• A-6 (creative direction). The visual, typographic, shape, layout, and motion specifications in Sections 6–8 are authoritative for presentation and do not add product behavior.

12. Glossary

• Calculator User — the single active human persona; the person performing arithmetic on the page.
• Expression — the ordered operands and operators entered since the last clear, shown in the display's upper line.
• Entry — the number currently being typed, before it is committed by an operator or equals.
• Result — the evaluated value of the expression, shown in the display's lower line.
• AC — the clear key that returns the page to the empty starting state from any state, including error.
• Active operator — the operator key currently selected, shown with a solid accent fill.
• Pixel-corner notch — a single 4px square cut from two opposite corners of the calculator panel.
• Hard offset shadow — a 3px shadow with no blur that snaps to zero on key press.