System Requirements Document for brave-calculator

1. Introduction

brave-calculator is a simple calculator delivered as a single page. The product intent is narrow and deliberate: one page that presents the calculator's design and interface so that a person can enter numbers and operations and see the computed result, without navigating anywhere else.

The audience is anyone who needs to add, subtract, multiply or divide — a plain, useful tool with no brand, no login and no audience beyond someone who needs basic arithmetic. The design register is warm and editorial: a small, calm, considered utility that feels like a page from a well-set book rather than a gadget demo or a SaaS dashboard.

The single page is the anonymous public entry to the product. It explains nothing beyond itself and requires no account, no identity and no persistence.

2. System Overview

brave-calculator is a single-page web calculator. The page is the entire product surface: a masthead line, a display block showing the pending expression and the running result, a hairline rule, a 4×5 keypad grid, and a single-line operation-history strip beneath the keypad. There is no navigation, no secondary destination, no account, and no server-side record of what the user calculates.

Current delivery comprises three provisioned services:

• frontend — a React application that renders the single Calculator page and performs arithmetic in the browser.
• backend — a shared FastAPI process reserved for application APIs and domain modules. No current requirement in this document calls a backend endpoint; the calculator's arithmetic and history are client-side state on the single page.
• database — MariaDB for application-owned persistent data. No current requirement in this document creates, reads or writes application-owned persistent data; the provisioned database does not by itself justify domain entities, authentication or a data model.

Actors:

• Calculator user (active human persona) — enters numbers and operations and reads the computed result on the single page.
• frontend (system actor) — evaluates the entered expression and renders the display, keypad and history strip.
• backend and database (system actors) — provisioned infrastructure, not engaged by any current accepted behavior.

Accepted behavior is confined to: entering digits and a decimal point, choosing one of the four operations, committing with equals, clearing, and reading the running result and the operation-history strip. Access is anonymous and public; no identity is established, verified or required.

Removed from scope

• None. The authoritative requirement thread contains no removed concepts.

2a. Product Interpretation and Delivery Boundary

The product is one page and one page only. The user asked for "simple single page of design of calculator," and the planning scope fixes an exact page count of one. That constraint is hard: there is no second route, no settings surface, no about page, no help page, and no account or sign-in flow. Everything the calculator does happens inside the Calculator page.

Access is anonymous and public. The page loads for anyone and requires no identity, no session and no stored profile. Because no accepted behavior creates a durable relationship, obligation, entitlement, value transfer or decision that must remain bound to a particular person, application-owned identity is neither required nor introduced. There is no first-use identity establishment, no returning verification, and no protected state.

Arithmetic and the operation-history strip are client-side state on the single page. The provisioned backend and MariaDB services exist as infrastructure inventory but carry no current product responsibility; no requirement in this document depends on them. Nothing about the calculator is persisted across reloads, and no future section of this document commits to persistence.

The delivery boundary is therefore: a first-party React page, publicly reachable, self-contained, with no provider-owned or external-destination surface and no background system process that a user interacts with.

2c. Page Content and Component Coverage

Calculator

The single page of the product, and the anonymous public entry. It is a narrow centred column (max-width 440px) on a warm cream field, with real margins at every viewport.

Information and state

• Masthead line — the quiet running head "A small calculator" in Literata 600, set tight, top-left of the column, with a small hand-drawn-feeling rust underline (SVG rule, slight wobble, 2px, 96px wide) as the page's only ornament.
• Pending expression — the expression entered so far (operands and the chosen operator), in muted 15px Work Sans, displayed above the running result.
• Running result — the current value, right-aligned with tabular figures, in Literata 500 at clamp(44px, 9vw, 96px), in ink #241F1A. This is the dominant element of the display block.
• Active operator state — the currently selected operation key is marked with the rust #A6482B accent so the user can see which operation is pending.
• Operation-history strip — a single-line, horizontally scrollable row beneath the keypad showing completed operations as small ledger entries, in 13px Work Sans 500 uppercase with 0.12em tracking, on a 6px-radius strip with mustard #C98A2E ticks.
• Empty state — on first load the running result reads 0, the pending expression is blank, and the history strip is empty (the strip may be visually collapsed to its hairline while empty).

Primary actions

• Digit keys (0–9) — append the digit to the current operand.
• Decimal key — appends a decimal point to the current operand; stays square so the grid reads as a printed table.
• Operation keys (+, −, ×, ÷) — set the pending operation and mark the key as active in rust.
• Equals key — the single rust #A6482B block in the whole interface, with cream numerals; commits the pending operation, computes the result, and appends the completed operation to the history strip.

Supporting actions

• Clear key — resets the current entry, the pending expression and the running result to the initial empty state. (The history strip is a record of completed operations and is not cleared by the clear key.)

Domain entities

• Expression — the pending operand, operator and second operand held in page state.
• Result — the numeric value produced by committing an expression.
• History entry — a completed operation recorded as a short expression-and-result pair, held in page state for the current visit only.

Component responsibilities

• Masthead — renders the running head and the rust underline; decorative only, no interaction.
• Display block — renders the pending expression and the running result; owns the cross-fade of the result when it changes.
• Keypad grid — a 4×5 grid of flat paper keys with 10px radius and 1px ink-tinted borders; dispatches digit, decimal, operation, equals and clear input; owns the 1px depress and #EADFCC darkening on press.
• History strip — renders completed operations as a horizontally scrollable ledger line; owns the 8px slide-in from the right when a new operation lands.

States

• Loading — the page is a static client-rendered surface; there is no data fetch and therefore no loading state beyond the initial render of the empty calculator.
• Empty — result 0, blank expression, empty history strip.
• Success — a committed operation shows its result in the display and its entry in the history strip.
• Error — division by zero is the only arithmetic failure the four operations can produce; the display shows an error indication in place of a result and the pending expression remains visible so the user can see what failed.
• Recovery — the clear key returns the page to the empty state from any state, including the error state; the user can then begin a new calculation. The history strip remains readable and scrollable throughout.

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts and observable acceptance.

FR-1 — Single-page calculator surface As a Calculator user, I should get the whole calculator on one page, so that I never have to navigate to use it.

• Provenance: explicit.
• Trigger: the user opens the product.
• Observable result: the Calculator page renders the masthead, display block, keypad grid and history strip; there is no other route, link or navigation control.
• Access state: anonymous and public; no identity required.
• Failure/recovery: not applicable — the page is static and self-contained.
• Continuation: the user proceeds directly to entering numbers.

FR-2 — Enter digits and a decimal point As a Calculator user, I should enter digits and a decimal point, so that I can build the numbers I want to calculate with.

• Provenance: required_inference (indispensable mechanics of "performing calculations" on the accepted single page).
• Trigger: the user presses a digit key or the decimal key.
• Observable result: the digit or decimal point appears in the pending expression and the running result updates to the number being entered.
• Access state: anonymous.
• Failure/recovery: a second decimal point in the same operand is not appended; the operand keeps its existing value.
• Continuation: the user may press an operation key to continue the expression.

FR-3 — Choose an operation As a Calculator user, I should choose addition, subtraction, multiplication or division, so that I can tell the calculator what to do with my numbers.

• Provenance: required_inference (indispensable mechanics of "performing calculations").
• Trigger: the user presses one of the four operation keys.
• Observable result: the chosen operation is recorded in the pending expression and its key is marked active in rust #A6482B.
• Access state: anonymous.
• Failure/recovery: pressing a different operation key before committing replaces the pending operation and moves the active marking to the new key.
• Continuation: the user enters the second operand and presses equals.

FR-4 — Commit with equals and read the result As a Calculator user, I should press equals and see the computed result, so that I get the answer to my calculation.

• Provenance: required_inference (indispensable mechanics of "performing calculations" and the accepted computed result).
• Trigger: the user presses the equals key with a complete expression.
• Observable result: the running result updates to the computed value in large Literata with tabular figures, cross-fading over 180ms; the completed operation is appended to the history strip, sliding in 8px from the right.
• Access state: anonymous.
• Failure/recovery: if the expression is incomplete (no second operand), equals does not commit and the display is unchanged. If the operation is division by zero, the display shows an error indication in place of a result and the pending expression stays visible.
• Continuation: the result becomes the starting value for a further operation, or the user clears to start again.

FR-5 — Read the operation-history strip As a Calculator user, I should see a single-line record of the operations I have completed, so that I can follow what I have just done.

• Provenance: required_inference (observable result of committing an operation on the accepted single page).
• Trigger: each successful equals commit.
• Observable result: a new entry appears at the right end of the history strip; the strip scrolls horizontally so every entry can be brought fully into view.
• Access state: anonymous.
• Failure/recovery: the strip is empty on first load and remains a static, horizontally scrollable row under prefers-reduced-motion.
• Continuation: the user reads the strip and continues calculating.

FR-6 — Clear and start again As a Calculator user, I should clear the current calculation, so that I can recover from a mistake or an error and start fresh.

• Provenance: required_inference (material recovery for the accepted calculation lifecycle).
• Trigger: the user presses the clear key.
• Observable result: the pending expression is blank, the running result reads 0, and the active operator marking is removed.
• Access state: anonymous.
• Failure/recovery: clear works from every state, including the division-by-zero error state.
• Continuation: the user begins a new calculation.

4. User Personas

Calculator user

Product context. The Calculator user arrives at a plain single-page calculator with no brand, no login and no audience beyond someone who needs to add, subtract, multiply or divide. They are not being onboarded, sold to, or asked to create an account. The page is the whole product, and the emotional register they meet is unhurried and humane — a small useful tool rather than a gadget demo.

Primary goal. Perform a basic arithmetic calculation and read the answer, on one page, without navigating anywhere.

Distinct accepted responsibilities.

• Enter the numbers of the calculation using the digit and decimal keys.
• Choose exactly one of the four operations — addition, subtraction, multiplication or division — and see which one is pending.
• Commit the calculation with the equals key and read the computed result.
• Read the operation-history strip to follow the operations just completed.
• Clear the current calculation to recover from a mistake or an error and start again.

Relevant inputs and decisions. Which digits and decimal point to enter; which of the four operations to apply; when to commit with equals; when to clear. The user makes every decision on this page — there is no counterparty, approver or administrator.

Interactions with other accepted participants. None. The Calculator user is the only active human participant. The frontend evaluates the expression and renders the result, but it is a system actor, not a participant with its own side of the lifecycle. No other persona is affected by, awaits, or receives anything from the user's calculation.

Observable success. The page loads and basic arithmetic can be performed without navigating elsewhere: the running result shows the computed value in large typeset numerals, the completed operation appears in the history strip, and the user can clear and begin again.

What makes this role's work different. It is a single, self-contained, anonymous act of arithmetic. There is no shared state, no handoff, no commitment to another party, and nothing to resume later. The role's entire responsibility begins and ends inside one visit to one page.

5. Core User Flows

Flow 1 — Perform a calculation and read the result

1. Starting context. The Calculator user opens the product in a browser. No identity is required and none is established.
2. Entry. The Calculator page renders: the masthead "A small calculator" with its rust underline, the display block showing 0 with a blank pending expression, the hairline rule, the 4×5 keypad grid, and an empty history strip.
3. Input — first operand. The user presses digit keys (and the decimal key if needed). Each digit appears in the pending expression and the running result updates to the number being entered.
4. Decision — operation. The user presses one of the four operation keys. The operation is recorded in the pending expression and that key is marked active in rust #A6482B. If the user changes their mind, pressing a different operation key replaces the pending operation and moves the active marking.
5. Input — second operand. The user presses digit keys for the second number; the pending expression shows both operands and the operator.
6. Commit. The user presses the equals key — the single rust block in the interface. The frontend evaluates the expression.
7. Observable result. The running result cross-fades over 180ms to the computed value, set right-aligned in large Literata with tabular figures. The completed operation slides into the history strip from the right as a new ledger entry.
8. Continuation. The user either continues by choosing another operation on the result, or presses the clear key to return to the empty state and begin a new calculation.

Flow 2 — Recover from division by zero

1. Starting context. The user has entered a first operand, chosen division, and entered 0 as the second operand.
2. Commit. The user presses equals.
3. Observable result. The display shows an error indication in place of a result; the pending expression remains visible so the user can see which calculation failed. No history entry is added for the failed operation.
4. Recovery. The user presses the clear key. The pending expression clears, the running result reads 0, and the active operator marking is removed.
5. Continuation. The user begins a new calculation from the empty state.

Flow 3 — Review completed operations in the history strip

1. Starting context. The user has completed one or more calculations in the current visit; the history strip holds their entries.
2. Action. The user reads the strip beneath the keypad, or scrolls it horizontally to bring earlier entries fully into view.
3. Observable result. Each completed operation is readable as a short ledger entry in small uppercase type with mustard ticks.
4. Continuation. The user returns to the keypad and continues calculating. Under prefers-reduced-motion, the strip remains a static, horizontally scrollable row with no slide-in animation.

6. Visuals Colors and Theme

The creative direction is authoritative for this section: Warm editorial arithmetic after Frank Chimero, with the headline idea that the page is a warm cream sheet of paper on which a small calculator is set like a printed table — the empty margins are the composition.

Color tokens (light mode only; no dark mode)

No blue anywhere; no gradients.

Typography

• Headings: Literata — 600 weight, set tight (−0.02em) for the small masthead line; 500 weight, 0.02em tracking, for the running result display.
• Body and controls: Work Sans.
• Scale: 1.25 modular, mobile-first — 44 / 36 / 24 / 18 / 15 / 13.
• Running result: clamp(44px, 9vw, 96px) in Literata 500 with tabular figures.
• Key labels: 22px Work Sans 500.
• Micro-labels and history: 13px Work Sans 500, uppercase, 0.12em tracking.

Shape language. Soft, honest rectangles: 14px radius on the calculator body, 10px on keys, 6px on the small history strip. One hairline 1px rule in #D8CBB8 under the masthead and above the keypad. Keys are flat paper with a 1px ink-tinted border; no drop shadows, no glass, no pills. The decimal key stays square so the grid reads as a printed table.

Layout. Single centred column, max-width 440px, on the warm cream field with real margins — 32px at 375px, 48px at 768px, generous air at 1280px where the column stays narrow and the page breathes. Order: masthead line top-left, display block (expression in muted small type above, running result in large Literata), hairline rule, 4×5 keypad grid, single-line operation-history strip.

Imagery. No photography and no illustration. The imagery is typographic and diagrammatic: the display is the subject, the keypad is the diagram, and the only ornament is the small hand-drawn-feeling rust underline beneath the masthead (SVG rule with a slight wobble, 2px, 96px wide). Optionally, a tiny ink spot illustration of a pencil in the empty right margin at 1280px only, decorative and aria-hidden.

Explicitly avoided. Blue or indigo accents on white; glassmorphism, frosted panels, gradient blobs or floating card shadows; Inter, Roboto, Arial, Helvetica, Poppins or system-ui for any type; a centred marketing headline with subtext and a CTA above the calculator; drop shadows on keys or hover-lift animations; dark mode, neon glows or techno monospace numerals; illustrated characters or stock photography; treating the calculator as a SaaS product with feature sections below the fold.

7. Signature Design Concept

The first screen is a warm cream page, not a hero banner. A narrow centred column (440px max) holds a small masthead line top-left in Literata 600 — "A small calculator" — underscored by a single hand-drawn rust rule with a slight wobble. Below it sits a large paper-surface display card whose dominant element is the running result, set at clamp(44px, 9vw, 96px) Literata 500 in ink, right-aligned with tabular figures, with the pending expression in muted 15px Work Sans above it. A hairline rule separates the display from a 4×5 keypad of flat paper keys with ink-tinted borders. The equals key is the single rust #A6482B block with cream numerals — the only hot accent in the whole interface, making the commit action unmissable without a second accent. The rest of the viewport is empty cream with generous margins; the emptiness is the composition.

The concept recomposes only accepted content and controls: the masthead, the expression and result display, the keypad, and the history strip. It introduces no new behavior, page or destination.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject. The running result in the display block — large Literata numerals, right-aligned with tabular figures, on the paper surface — with the rust equals key as the single hot accent below it.
• Input → transformation → outcome thesis. A key press depresses 1px and darkens to #EADFCC over 120ms; the pressed digit or operation appears in the pending expression; on equals, the result cross-fades over 180ms to the computed value and the completed operation slides 8px in from the right into the history strip. The transformation is the arithmetic itself; the outcome is a typeset number and a new ledger line.
• Motion vocabulary. Restrained and print-like: 1px key depress with a 120ms darkening, a 180ms result cross-fade, an 8px history slide-in from the right. No bounce, no particles, no count-up animation.
• Composed first frame. Warm cream field, narrow 440px column, masthead top-left with its rust underline, display showing 0 with a blank expression, hairline rule, flat paper keypad, empty history strip. No centred headline, no subtext, no gradient, no button stack.
• Reduced-motion state. With prefers-reduced-motion, all transitions become instant state changes: keys change state without the depress animation, the result swaps without a cross-fade, and the history strip remains a static, horizontally scrollable row.

9. Non-Functional Requirements

• Single-page constraint (explicit). The calculator must be a single page. There is exactly one page and no other route, navigation control or secondary destination.
• Anonymous public access (explicit). The page requires no account, no sign-in and no identity of any kind. No authentication, session or profile is introduced.
• No persistence (required_inference). Because no accepted behavior creates a durable relationship, obligation, entitlement or value transfer bound to a person, the calculator's expression, result and history live only in page state for the current visit. Nothing is written to the provisioned database.
• Readable text and controls at every viewport (explicit). Headlines, labels, numbers 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, with no other element covering any part of them. The history strip may scroll horizontally by design; every entry becomes fully readable as it passes.
• Reduced-motion support (explicit). Under prefers-reduced-motion, all transitions become instant state changes and the history strip remains a usable static, horizontally scrollable row.
• Accessible contrast and focus (required_inference). Ink #241F1A on cream #FBF7EF and cream numerals on rust #A6482B meet readable contrast; the focus ring uses mustard #C98A2E so keyboard users can see which key is focused.
• No blue or indigo (explicit). The generic indigo/blue-on-white SaaS template is forbidden for this project.

10. Tech Stack

• Frontend: React application rendering the single Calculator page; arithmetic and history are client-side state. Typography loads Literata and Work Sans.
• Backend: shared FastAPI process, provisioned as the application API and domain-module host. No current requirement in this document calls it; it is preserved as inventory and as the natural home for any future API work.
• Database: MariaDB, provisioned for application-owned persistent data. No current requirement creates, reads or writes application-owned persistent data.
• Containerization: docker-compose with the three provisioned services — frontend, backend, database — each shown explicitly with its supported connections.

11. Assumptions and Constraints

• Assumption (narrow). The four operations are addition, subtraction, multiplication and division, as named in the creative direction's reading of the brief. No other mathematical function is in scope.
• Assumption (narrow). The calculator evaluates a single pending binary operation at a time; chained entry continues from the previous result rather than introducing an expression parser with operator precedence.
• Assumption (narrow). The history strip records completed operations for the current visit only and is not cleared by the clear key, which resets the current calculation.
• Constraint (explicit). The product is a single page; the page count is exactly one.
• Constraint (explicit). The page is anonymous and public; no identity, account or session is introduced.
• Constraint (explicit). The palette, fonts, surfaces, tone and layout of the creative direction are preserved; the generic indigo/blue-on-white SaaS template is forbidden.
• Constraint (explicit). The provisioned backend and MariaDB services do not by themselves justify domain entities, authentication or a data model, and none is introduced.

12. Glossary

• Calculator page — the single page of the product and its anonymous public entry; the only destination.
• Calculator user — the single active human persona; performs arithmetic on the Calculator page.
• Pending expression — the operands and chosen operator entered so far, shown in muted small type above the running result.
• Running result — the current value shown in large Literata with tabular figures; the dominant element of the display block.
• Active operator — the currently selected operation key, marked in rust #A6482B.
• Equals key — the single rust #A6482B block in the interface; commits the pending operation.
• Operation-history strip — the single-line, horizontally scrollable ledger of completed operations beneath the keypad.
• Clear key — resets the current calculation to the empty state.
• Empty state — result 0, blank expression, empty history strip.