System Requirements Document for bold-calculator

1. Introduction

bold-calculator is a single-page calculator design: one calm, precise surface where a visitor performs everyday arithmetic. The product intent is deliberately narrow — a small, high-frequency utility that must feel trustworthy, instantly legible, and engineered rather than templated. The audience is any everyday user who needs a quick calculation without ceremony: they open the page, enter numbers and operators, read the result, and clear or correct the entry to begin again.

The design language is "Quiet precision, one perfectly lit keypad," drawing on the restraint and material honesty of Jony Ive's instrument design: a graphite ground, a single studio-lit calculator body, aluminium-plate keys, hairline dividers, and one champagne accent reserved for the equals key and the active operator state.

2. System Overview

bold-calculator is delivered as a single custom page, Calculator, which is the anonymous public entry surface. There is no account, no sign-in, and no persisted user data: the page is a self-contained instrument.

Current delivery comprises:

• Frontend (React application UI) — renders the single Calculator page: the slim wordmark rail, the calculator body with its full-width right-aligned result readout, the strict 4-column keypad (zero key spanning two columns), and the hairline-ruled footer of one-line hints. All arithmetic entry, display, and clearing happen in this surface.
• Backend (shared FastAPI process) — the provisioned shared application process for application APIs and domain modules. The accepted calculator behavior is a client-side interaction on a single page; the backend remains available as the shared process for any application API the implementation requires, and is not itself a product capability.
• Database (MariaDB) — provisioned application-owned persistent storage. The accepted requirements create no durable user records, accounts, or saved calculations, so no domain entities are derived from it.

Actors:

• Calculator User (active human persona) — the single visitor who enters numbers and operators, reads the running result, and clears or corrects the entry.
• Frontend application (system) — evaluates and displays the arithmetic state.
• Shared backend process and MariaDB (system infrastructure) — provisioned services, not persona-facing capabilities.

Narrow exclusions: no accounts, no saved history, no sharing, no scientific or programmer modes, no unit conversion, no multi-page navigation. The design is a single page.

Removed from scope

• None. No concept was explicitly removed by the user.

2a. Product Interpretation and Delivery Boundary

The requester asked for a simple single-page calculator design. That is the whole current product: one page, one instrument, everyday arithmetic. The page is publicly reachable with no identity step — there is nothing private to own, resume, or protect, so no account establishment, verification, or session continuity is introduced. Access is anonymous and ephemeral by design.

Everything the Calculator User does — entering digits, choosing an operator, reading the result, clearing the entry — happens on the single Calculator page. The shared backend and MariaDB are provisioned infrastructure that the implementation may use for application APIs; they do not add user-facing workflows, and the accepted behavior does not require durable records.

Future ideas are not part of the current product and are not represented on the page. The single-page constraint is binding: no additional destinations are introduced.

2c. Page Content and Component Coverage

Calculator

The single page and anonymous public entry surface. It presents the calculator as one studio-lit object on a graphite ground, with an editorial headline block in dialogue with it at wide viewports.

Information and state

• Current entry string (digits and decimal point as typed).
• Pending operator and the stored left operand, when an operator has been chosen.
• The result readout: the current entry or the computed result, right-aligned, tabular numerals, full width of the calculator body.
• Active operator state: the currently selected operator key is highlighted in champagne.
• Error state: an invalid operation (for example division by zero) surfaces a clear, legible error in the readout rather than a silent or garbled value.

Primary actions

• Digit keys 0–9 append digits to the current entry; the zero key spans two columns in the 4-column grid.
• Decimal point key begins or extends a fractional entry.
• Operator keys (add, subtract, multiply, divide) set the pending operator and highlight that key in champagne.
• Equals key (the only champagne surface on the page) evaluates the pending operation and shows the result.
• Clear key resets the entry and pending operation to a fresh state.

Supporting actions and content

• Slim top rail with the wordmark in 300-weight Inter Tight at 20px and a hairline rule running the full viewport width.
• At ≥1024px, an asymmetric editorial split: the left 42% holds the oversized light-weight headline "Numbers, / quietly / precise." in three tight lines with a hairline rule and a one-line caption beneath; a hairline vertical rule separates it from the calculator body in the right 58%. Below 1024px the headline collapses to a compact two-line block above the calculator, which becomes the full-width hero.
• Hairline-ruled footer of one-line hints.

Domain entities

• Calculation state: current entry, stored operand, pending operator, displayed result, error flag. This state is in-memory for the session; nothing is persisted.

Component responsibilities

• Wordmark rail: identity and engraved-bezel framing.
• Headline block: editorial context at wide viewports; collapses above the calculator at narrow viewports.
• Calculator body: squircle 36px radius, hairline 1px top-edge highlight, one soft ambient shadow, floating in graphite negative space; contains the readout and keypad.
• Result readout: oversized right-aligned tabular numerals that shrink with a subtle scale transition as digits grow so they never overflow.
• Keypad: strict 4-column grid of flat 22px-radius aluminium-plate keys with 1px rgba(255,255,255,0.08) hairlines; operator column slightly lighter; equals key in champagne.
• Footer hints: hairline-ruled one-line guidance.

States

• Loading: the calculator body fades and rises 12px on load (700ms, cubic-bezier(0.22,1,0.36,1)); under prefers-reduced-motion it appears in its final position with no motion.
• Empty/initial: readout shows a zero entry, no operator active.
• Success: the computed result is displayed correctly in the readout.
• Error: invalid operations show a legible error message in the readout; the Clear key returns the page to the initial state.
• Recovery: Clear resets entry, operator, and error so the user can start a new calculation immediately.

3. Functional Requirements

FR-1 — Single-page calculator design (explicit) As a Calculator User I should see the entire calculator on one single page, so that I can perform arithmetic without navigating anywhere.

• Trigger: the user opens the page.
• Observable result: the Calculator page renders the wordmark rail, the calculator body with readout and keypad, and the footer hints; no other page or route is part of the product.
• Access: anonymous, no identity step.
• Failure/recovery: if the page fails to render, reloading restores the same single page; there is no alternate destination.
• Continuation: the user proceeds directly to entering a calculation.

FR-2 — Perform basic arithmetic (explicit) As a Calculator User I should enter numbers and operators and see the result, so that I can complete everyday calculations.

• Trigger: the user presses digit keys, an operator key, and the equals key.
• Observable result: the readout shows the current entry as typed, the chosen operator key highlights in champagne, and pressing equals displays the computed result right-aligned in the readout.
• Access: anonymous.
• Failure/recovery: an invalid operation (for example division by zero) shows a legible error in the readout; the Clear key restores a fresh state.
• Continuation: the user can chain further operations from the displayed result or clear and start again.

FR-3 — Clear and correct the entry (required_inference) As a Calculator User I should clear the current entry and pending operation, so that I can correct a mistake or start a new calculation.

• Trigger: the user presses the Clear key.
• Observable result: the readout returns to the initial zero entry, no operator is active, and any error state is dismissed.
• Access: anonymous.
• Failure/recovery: not applicable beyond the reset itself; Clear always returns the page to the initial state.
• Continuation: the user begins a new calculation immediately.

FR-4 — Legible result readout at every viewport (required_inference) As a Calculator User I should always read the full result and every key label, so that I can trust the displayed value.

• Trigger: the user enters digits or a result is computed, at 375px, 768px, or 1280px.
• Observable result: the readout scales down with a subtle transition as digits grow so it never overflows the calculator body; all key numerals, labels, and the wordmark stay entirely inside the viewport and their containers.
• Access: anonymous.
• Failure/recovery: if a value would exceed the readout, it scales rather than clipping; no readable text or control is covered by decoration.
• Continuation: the user continues entering or clears.

4. User Personas

Calculator User

Product context. An everyday visitor who reaches for a calculator as a small, high-frequency utility. They arrive with a specific sum in mind and expect the instrument to be immediately legible — no onboarding, no account, no explanation needed.

Primary goal. Complete an everyday arithmetic calculation quickly and read a correct result with confidence.

Distinct accepted responsibilities.

• Enter numbers and operators on the keypad.
• Read the running entry and the computed result in the oversized right-aligned readout.
• Clear or correct the entry to start a new calculation.

Relevant inputs and decisions. Which digits and decimal point to enter; which operator (add, subtract, multiply, divide) to apply; when to press equals; when to clear. The user decides when a calculation is complete and when to begin another.

Interactions with other participants. The Calculator User is the only active human participant. The frontend application evaluates and displays the arithmetic state; the shared backend and MariaDB are infrastructure and do not interact with the user.

Observable success. The displayed result is correct, fully readable at any viewport, and the user can immediately clear and start the next calculation. The experience feels calm, precise, and trustworthy — an engineered instrument rather than a templated widget.

5. Core User Flows

Flow 1 — Perform a basic calculation

1. The Calculator User opens the page. The Calculator page renders; the calculator body fades and rises 12px into place (or appears statically under prefers-reduced-motion). The readout shows the initial zero entry.
2. The user presses digit keys to enter the first number. The readout shows the entry right-aligned in tabular numerals, scaling down if digits grow.
3. The user presses an operator key. That key highlights in champagne, and the pending operator is set.
4. The user enters the second number; the readout shows it.
5. The user presses the champagne equals key. The frontend evaluates the pending operation and the readout displays the result.
6. Success: the correct result is fully readable. Continuation: the user may chain another operation from the result or press Clear to start fresh.

Flow 2 — Correct a mistake or start over

1. The user is mid-entry or has an error in the readout (for example division by zero).
2. The user presses the Clear key.
3. The readout returns to the initial zero entry, no operator is active, and any error is dismissed.
4. Continuation: the user begins a new calculation immediately.

Flow 3 — Read the result at any viewport

1. The user opens the page at 375px, 768px, or 1280px.
2. At 1280px the headline block sits to the left of the calculator body across a hairline vertical rule; below 1024px the headline collapses to a compact two-line block above the full-width calculator.
3. The user enters a long value; the readout scales with a subtle transition so it never overflows, and all key labels and the wordmark remain entirely inside the viewport.
4. Success: every readable element is whole and legible; the user continues or clears.

6. Visuals Colors and Theme

Muse and headline. Jony Ive — "Quiet precision, one perfectly lit keypad." The interface itself is the subject: one precisely lit calculator body on a graphite ground.

Palette (dark mode)

Proportion: 80% dark neutrals, 15% light aluminium type, 5% champagne accent — the accent is a signal, never a field.

Typography. Headings and body: Inter Tight. Wordmark and section labels at Light 300 weight, tight -0.03em tracking; uppercase micro-labels at 11px with 0.18em letterspacing. The result display is the hero: light weight, tabular numerals, enormous scale, right-aligned like an instrument readout. Scale: 1.25 modular with a display outlier — display 44px mobile → 120px desktop (clamp), wordmark 20/18/16, labels 11, button numerals 26/28/30, body 15/16, caption 12.

Shape language. Soft continuous-curve radii (squircle-like): 22–28px on keys, 36px on the calculator body. Hairline 1px dividers in rgba(255,255,255,0.08). No shadows except one soft ambient lift under the calculator body. Keys are flat aluminium plates, not glossy buttons.

Layout. Single-column, product-first composition: slim wordmark rail at top, calculator body centred in generous negative space, hairline-ruled footer of one-line hints. Display at the top of the calculator body as a full-width right-aligned readout; keypad in a strict 4-column grid with the zero key spanning two columns. At 375px the calculator body fills the viewport minus 20px gutters; at 768px it caps at 420px wide; at 1280px it sits at 460px with the headline block to its left in an asymmetric two-column editorial split.

Imagery. No photography, no illustration. A single soft radial highlight rgba(255,255,255,0.06) falls across the top-left of the body as if from a studio softbox; macro detail expressed through hairlines and the champagne equals key.

Avoid. Blue/indigo accents or white-ground layouts; gradient-blob heroes or glassmorphism; drop shadows on individual keys or glossy skeuomorphic buttons; Inter, Roboto, Arial or system-ui as the visible type; playful bounce or springy key animations; stock photography or decorative illustration; a grid of identical hover-lift cards; the centred headline + subtext + coloured CTA hero pattern.

7. Signature Design Concept

The public entry is a single studio-lit instrument. At 1280px the viewport splits asymmetrically: the left 42% holds an oversized light-weight Inter Tight headline stacked in three tight lines — "Numbers, / quietly / precise." — at clamp 44px → 120px, with a single hairline rule and a one-line caption beneath; a hairline vertical rule separates it from the right 58%, which holds the calculator body as the dominant, perfectly lit object floating on the graphite ground with one soft ambient shadow. At 375px and 768px the headline collapses to a compact two-line block above the calculator, which becomes the full-width hero.

Signature moves: an oversized right-aligned tabular-numeral result readout filling the full width of the calculator body at clamp 44px → 120px, shrinking with a subtle scale transition as digits grow so it never overflows; a calculator body treated as a single studio-lit object with squircle 36px radius, hairline 1px top-edge highlight, and one soft ambient shadow; a keypad of machined aluminium plates with the operator column slightly lighter and the equals key as the only champagne surface; a slim top rail with the 300-weight wordmark and a full-width hairline rule echoing an engraved bezel. The concept recomposes only accepted content and controls — the readout, the keypad, the Clear and equals keys — and introduces no new behavior.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the calculator body as a single studio-lit object on the graphite ground, with a soft radial highlight across its top-left.
• Input → transformation → outcome thesis: on load, the calculator body fades and rises 12px into place with a slow physical ease (cubic-bezier(0.22,1,0.36,1), 700ms), settling as the perfectly lit instrument; thereafter each key press gives instant 90ms tactile feedback — a 1px inset and a brief champagne glow on the active operator — so the instrument responds like machined hardware.
• Motion vocabulary: one purposeful reveal; instant tactile key feedback; no bounce, no particles, no parallax.
• Composed first frame: graphite ground, slim wordmark rail with hairline rule, headline block left, calculator body right with initial zero readout, all at rest before the reveal.
• Reduced-motion state: the calculator body appears in its final position with no rise or fade; key feedback remains a static inset state; the page is fully usable.

9. Non-Functional Requirements

• Single-page constraint (explicit): the product is one page; no additional routes or destinations are introduced.
• Legibility at every viewport (explicit, from creative direction): headlines, wordmarks, labels, numbers, and controls stay entirely inside the viewport and their containers at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...)) to fit; no other element covers any part of them.
• Reduced motion (explicit, from creative direction): with prefers-reduced-motion, provide a usable static arrangement — the calculator appears in its final position with no reveal animation.
• Accessibility of contrast and type (required_inference): near-white #F2F2F0 on graphite #111214 and champagne #C8A96A on #1B1D20 maintain readable contrast; tabular numerals keep the readout stable as digits change.
• No persistence of user data (required_inference): calculation state is in-memory for the session; no accounts, history, or saved calculations are created.
• Performance (required_inference): key feedback is instant (90ms) and the page loads as a single lightweight surface.

10. Tech Stack

• Frontend: React application UI rendering the single Calculator page.
• Backend: shared FastAPI process for application APIs and domain modules (provisioned; not a product capability for the accepted calculator behavior).
• Database: MariaDB for application-owned persistent data (provisioned; no domain entities derived from the accepted requirements).
• Containerization: Docker / docker-compose for the frontend, backend, and database services.
• Typography: Inter Tight (Light 300 for wordmark and labels; body and display), loaded as a web font.

11. Assumptions and Constraints

• A-1 (explicit): The design is a single page; the page count is exactly one.
• A-2 (explicit): The calculator supports basic arithmetic — addition, subtraction, multiplication, division — with digits, a decimal point, equals, and clear.
• A-3 (required_inference): Access is anonymous and ephemeral; no identity, account, or session continuity is required because there is no private or durable state.
• A-4 (required_inference): Calculation state lives in the browser session; the provisioned backend and MariaDB do not store user calculations.
• A-5 (required_inference): Invalid operations such as division by zero surface a legible error in the readout, recoverable via Clear.
• A-6 (default — not specified by user): The page is delivered as a React web application; no native mobile app is in scope.

12. Glossary

• Calculator page — the single page of the product; the anonymous public entry surface containing the wordmark rail, calculator body, and footer hints.
• Calculator body — the studio-lit squircle container holding the result readout and keypad.
• Readout — the oversized, right-aligned, tabular-numeral display of the current entry or computed result.
• Keypad — the strict 4-column grid of aluminium-plate keys, with the zero key spanning two columns.
• Active operator — the currently selected operator key, highlighted in champagne.
• Champagne accent — the brushed #C8A96A colour reserved for the equals key and the active operator state.
• Calculator User — the single active human persona who performs everyday arithmetic on the page.