System Requirements Document for rustic-calculator

1. Introduction

rustic-calculator is a simple calculator delivered as a single-page design. The product intent is narrow and explicit: one page, one instrument, everyday arithmetic. A person opens the page, enters numbers and operators, reads the running expression and the result, and clears the display to begin again.

The audience is anyone doing quick arithmetic — a student checking homework, a shopper totalling a basket, a freelancer running a figure. The page must feel like a well-made tool: legible at a glance, calm, warm, and trustworthy, with no account, no navigation, and no surrounding application shell.

The design language is a warm, Fira-set instrument panel inspired by Erik Spiekermann's typographic infrastructure work: a paper-warm ground, a single white calculator card, oversized tabular result numerals, a signal-orange operator band, and a mustard clear key.

2. System Overview

2a. Product Interpretation and Delivery Boundary

The product is a single, anonymously reachable calculator page. There is no sign-in, no account, no saved history, and no second destination. The page is the entire product surface: display area, keypad, and a quiet footnote.

All calculation behavior is first-party and runs in the browser on the single page. The provisioned backend and database services exist as scaffold infrastructure and are not required by any accepted calculator workflow; no calculator state is persisted, and no domain entities are created for this product. The single-page constraint is a hard boundary: no additional pages, routes, or destinations are introduced now or implied by the scaffold.

Future ideas are not part of the current product and are not represented on the page.

2b. Source Content Inventory

Not applicable — no reference directive supplies a content_source.

2c. Page Content and Component Coverage

Calculator

The sole page of the product, anonymously reachable, with no identity requirement.

Information and state

• Page-level small-caps label CALCULATOR above the card.
• Display area at the top of the card, separated from the keypad by a 1px warm hairline rule (#E3DCCF).
  • Micro-label EXPRESSION (11px, Fira Sans 500, tracked +0.12em, muted #7A736A).
  • Running expression line, right-aligned, muted grey (#7A736A), 18px desktop / 16px mobile.
  • Micro-label RESULT.
  • Result numeral, right-aligned, ink (#1F1D1A), Fira Sans Light 300, tabular figures, clamp(56px, 9vw, 128px), tight tracking.
• Keypad grid: 4 columns, consistent 12px gutter.
  • Digits 7-9 / 4-6 / 1-3 in white keys (#FFFFFF) with ink digits at Fira Sans 600, 24px desktop / 20px mobile.
  • Decimal point key.
  • Operator column on the right rendered as a continuous signal-orange (#E8501F) vertical band: ÷, ×, −, +.
  • Clear key in mustard (#F2B705), set apart from the operator band.
  • Equals key as a solid signal-orange block spanning the bottom-right.
• Below the card: a single hairline rule and a quiet footnote in muted grey.

Primary actions

• Press a digit key to append a digit to the current entry.
• Press the decimal point key to begin a fractional entry.
• Press an operator key to commit the current entry and select the operation.
• Press the equals key to evaluate the expression and show the result.
• Press the clear key to reset the expression and result.

Supporting actions

• Backspace/correction of the current entry (as provided by the clear key behavior described in the requirements).

Domain entities

• Expression: the running sequence of entered operands and operators shown in the expression line.
• Result: the evaluated numeric value shown in the oversized result numeral.
• Current entry: the operand being typed before an operator or equals is pressed.

Component responsibilities

• Display component: renders the expression line and result numeral; fades the result in over 120ms when it changes.
• Keypad component: renders the 4-column grid, the orange operator band, the mustard clear key, and the orange equals block; applies a 1px depress with 90ms ease-out on press.
• Footnote component: renders the hairline rule and muted footnote text.

States

• Loading: not applicable; the page renders immediately with an empty expression and a zero result.
• Empty: expression line blank, result showing 0.
• Success: expression line shows the entered sequence; result shows the evaluated value.
• Error: division by zero or an unparseable expression shows an error indication in the result area instead of a numeric value; the clear key returns the page to the empty state.
• Recovery: pressing clear at any time resets expression and result to the empty state; pressing an operator after an error starts a new expression.

3. Functional Requirements

FR-1 — Single-page calculator delivery (explicit) As a Calculator User I should reach the calculator as a single page so that all arithmetic happens in one self-contained surface.

• Trigger: opening the product.
• Observable result: one page renders with the CALCULATOR label, display area, keypad, and footnote; no navigation to other pages exists.
• Access: anonymous, no identity required.
• Failure/recovery: not applicable.
• Continuation: the user proceeds to enter digits.

FR-2 — Digit entry (explicit) As a Calculator User I should press digit keys so that the digits appear in the current entry and the expression line.

• Trigger: pressing a digit key (0–9).
• Observable result: the digit is appended to the current entry; the expression line reflects the entry.
• Access: anonymous.
• Failure/recovery: pressing clear resets the entry.
• Continuation: the user presses an operator or equals.

FR-3 — Decimal entry (required_inference) As a Calculator User I should press the decimal point key so that I can enter fractional values.

• Trigger: pressing the decimal point key.
• Observable result: a decimal point is added to the current entry; a second decimal point in the same entry is ignored.
• Access: anonymous.
• Failure/recovery: clear resets the entry.
• Continuation: the user continues typing digits or presses an operator.

FR-4 — Operator selection (explicit) As a Calculator User I should press an operator key so that the chosen operation is applied to the current entry.

• Trigger: pressing +, −, ×, or ÷ in the orange operator band.
• Observable result: the current entry is committed as an operand, the operator appears in the expression line, and a new entry begins.
• Access: anonymous.
• Failure/recovery: pressing clear discards the pending expression.
• Continuation: the user enters the next operand.

FR-5 — Evaluation (explicit) As a Calculator User I should press the equals key so that the expression is evaluated and the result is shown.

• Trigger: pressing the equals key.
• Observable result: the result numeral updates to the evaluated value and fades in over 120ms; the expression line retains the evaluated expression.
• Access: anonymous.
• Failure/recovery: division by zero or an unparseable expression shows an error indication in the result area; clear returns to the empty state.
• Continuation: the user may press an operator to continue from the result or press clear to start over.

FR-6 — Clear (explicit) As a Calculator User I should press the mustard clear key so that the expression and result reset.

• Trigger: pressing the clear key.
• Observable result: expression line is blank and the result shows 0.
• Access: anonymous.
• Failure/recovery: clear is always available, including after an error.
• Continuation: the user begins a new calculation.

FR-7 — Key press feedback (explicit) As a Calculator User I should see each key depress so that I know my press registered.

• Trigger: pressing any key.
• Observable result: the key depresses 1px with a 90ms ease-out; no bounce or elastic motion.
• Access: anonymous.
• Failure/recovery: not applicable.
• Continuation: the corresponding entry or operation proceeds.

4. User Personas

Calculator User

Product context. A person who opens the single-page calculator to perform everyday arithmetic — checking homework, totalling a basket, running a figure. They arrive with a number in mind and expect a legible instrument, not an application.

Primary goal. Get an accurate result from one self-contained page with minimal effort.

Distinct accepted responsibilities.

• Enter numbers and operators into the display.
• Read the running expression and the result.
• Clear or correct entries to start a new calculation.

Relevant inputs and decisions. Which digits and operators to enter; when to press equals; when to clear.

Interactions with other participants. None — the calculator is a single-user instrument with no counterparty, handoff, or shared state.

Observable success. The result numeral shows the correct value for the entered expression, and the user can clear and begin again without leaving the page.

5. Core User Flows

Flow A — Perform a calculation

1. The Calculator User opens the product. The Calculator page renders anonymously with the CALCULATOR label, an empty expression line, and a result of 0.
2. The user presses digit keys. Each digit appears in the current entry and the expression line; each key depresses 1px over 90ms.
3. The user presses an operator key in the orange band. The current entry is committed, the operator appears in the expression line, and a new entry begins.
4. The user enters the next operand.
5. The user presses the equals key. The result numeral updates to the evaluated value and fades in over 120ms; the expression line retains the evaluated expression.
6. Continuation: the user presses an operator to continue from the result, or presses the mustard clear key to reset to the empty state.

Flow B — Correct or restart

1. From any state on the Calculator page, the user presses the mustard clear key.
2. The expression line blanks and the result returns to 0.
3. The user begins a new calculation from step 2 of Flow A.

Flow C — Recover from an error

1. The user presses equals on an expression that divides by zero or cannot be parsed.
2. The result area shows an error indication instead of a numeric value.
3. The user presses the clear key; the page returns to the empty state.
4. The user re-enters the expression and presses equals again.

6. Visuals Colors and Theme

Muse and headline. Erik Spiekermann — typographic infrastructure for a calculator: a warm, Fira-set instrument panel.

Mode. Light only.

Colour tokens (exact hex by role)

• Background / ground: #F4F0E8
• Surface (calculator card, digit keys): #FFFFFF
• Text / ink (digits, labels, result): #1F1D1A
• Primary / signal orange (equals key, operator band): #E8501F
• Accent / mustard (clear key): #F2B705
• Muted (expression line, micro-labels, footnote): #7A736A
• Hairline rule: #E3DCCF

Proportions. ~70% ground, ~20% white surface, ~10% signal colour.

Typography

• Headings and numerals: Fira Sans. Display numerals at weight 300–400, tabular figures, tight tracking.
• Body: Fira Sans.
• Keypad digits: Fira Sans 600.
• Micro-labels (EXPRESSION, RESULT, CALCULATOR): Fira Sans 500, small caps, 11px, tracked +0.12em.
• No italic, no display serif.
• Scale (1.333 modular): display numerals clamp(56px, 9vw, 128px); page title 28/22px; keypad digits 24/20px; micro-labels 11px caps tracked +0.12em; expression line 18/16px.

Shape language. Modest rounded rectangles (8–12px radii) for keys; a single 20px-radius card for the calculator body; 1px warm hairline rules separating display from keypad and keypad from footnote. No blobs, no pills, no shadows beyond a single soft 0 2px 0 hairline under each key to suggest pressability.

Layout. Centred single column, max-width 480px on mobile and 560px on desktop, calculator card vertically centred in the viewport. Above the card, the small-caps CALCULATOR label. Inside the card: display area on top (expression line right-aligned in muted grey, result in oversized Fira Sans right-aligned in ink), then a 4-column keypad grid with a consistent 12px gutter — digits 7-9/4-6/1-3 in white keys, operators column on the right in signal orange, clear key in mustard, equals key spanning the bottom-right. Below the card, a single hairline rule and a quiet footnote in muted grey.

Imagery. No photography, no illustration. The interface itself is the image; the oversized numerals are the visual subject.

Avoid. Blue or indigo anywhere; gradient backgrounds, glassmorphism, blurred blobs; rounded pill buttons or oversized soft shadows; illustration, icons, or emoji on the keys; a centred marketing headline above the calculator; multiple accent colours scattered across keys; Inter, Roboto, or system-ui for any text; bouncy or elastic key animations.

7. Signature Design Concept

The public entry is the calculator itself. A warm paper ground (#F4F0E8) fills the viewport, and a single white calculator card floats dead centre at 560px wide on desktop. The dominant element is the oversized Fira Sans Light result numeral — up to 128px, right-aligned, in ink — sitting above a 4-column keypad where the operator column is a solid signal-orange vertical band and the equals key is a solid orange block. Above the card, a small tracked-caps CALCULATOR label; below it, a single hairline rule and a muted footnote. No blue, no gradient, no centred marketing headline — the calculator is the hero.

Signature moves carried into implementation:

• Oversized right-aligned result numeral in Fira Sans Light (clamp(56–128px)) with tabular figures — the number is the page's headline.
• Operator column rendered as a continuous signal-orange vertical band, not four separate keys, so arithmetic reads like a transit line down the right edge of the keypad.
• Small-caps micro-labels (EXPRESSION, RESULT) in 11px tracked Fira Sans 500, like wayfinding signage above the display.
• A single hairline warm rule under every key and under the display, giving the keypad the ruled, tabular quality of a printed timetable.
• The clear key in mustard (#F2B705) sits apart from the orange operator band — a second signal colour doing exactly one job.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the oversized right-aligned result numeral above the colour-coded keypad.
• Input → transformation → outcome thesis: a key press depresses the key 1px over 90ms ease-out; the corresponding digit or operator appears in the expression line; on equals, the result numeral fades in over 120ms to the evaluated value.
• Motion vocabulary: functional only — 1px key depress at 90ms ease-out; 120ms result fade-in on change. No bounce, no decorative loops.
• Composed first frame: warm paper ground, white card centred, CALCULATOR label above, empty expression line, result showing 0, orange operator band and mustard clear key visible.
• Reduced-motion state: key depress and result fade are suppressed; state changes appear instantly with the same layout and legibility.

9. Non-Functional Requirements

• Single-page constraint (explicit): the calculator design must be a single page; no additional routes or destinations.
• Simplicity (explicit): the design must remain simple — one instrument, no surrounding application shell.
• Legibility (explicit, from creative direction): readable text and controls stay whole at 375px, 768px, and 1280px, wrapping or scaling to fit, with no element covering them.
• Accessibility of motion (explicit, from creative direction): with prefers-reduced-motion, provide a usable static arrangement.
• No persistence (required_inference): calculator state is not stored; the provisioned database is not used by any accepted workflow.

10. Tech Stack

• Frontend: React application UI (provisioned).
• Backend: shared FastAPI process for application APIs and domain modules (provisioned; not required by accepted calculator workflows).
• Database: MariaDB for application-owned persistent data (provisioned; not used by accepted calculator workflows).
• Fonts: Fira Sans (weights 300, 400, 500, 600) for all text.
• Deployment: docker-compose with the provisioned frontend, backend, and database services.

11. Assumptions and Constraints

• The calculator supports the four basic operations (+, −, ×, ÷), digits 0–9, a decimal point, clear, and equals. (required_inference — the minimum set implied by "simple calculator".)
• The page is anonymously reachable with no identity requirement. (explicit via planning scope access requirement none.)
• No calculation history, memory keys, or scientific functions are included. (required_inference from "simple".)
• The provisioned backend and database remain available as scaffold but carry no calculator domain logic or entities.
• The design is light-mode only, per the creative direction.

12. Glossary

• Calculator User — the single active human persona who performs arithmetic on the page.
• Expression line — the muted, right-aligned line showing the running sequence of operands and operators.
• Result numeral — the oversized ink numeral showing the evaluated value.
• Operator band — the continuous signal-orange vertical column of operator keys on the right of the keypad.
• Clear key — the mustard key that resets expression and result.
• Micro-label — the 11px tracked small-caps label (CALCULATOR, EXPRESSION, RESULT).