System Requirements Document for misty-start

1. Introduction

misty-start is a simple calculator delivered as a single-page design. The product intent is narrow and exact: one page, one instrument, everyday arithmetic. A visitor arrives, enters numbers and operators, reads the result, and clears or corrects input to begin again — all without navigating away from the page.

The audience is anyone doing quick arithmetic who wants a calm, precise, trustworthy instrument rather than a toy or a marketing experience. There is no onboarding, no account, and no marketing gloss; the numbers are the product.

The page is anonymous and public. No identity, sign-in, or persistence is required or accepted.

2. System Overview

misty-start is a single-page calculator application. The current delivery consists of:

• A React frontend that renders the one accepted page, Calculator, and hosts all number/operator entry, result display, and clearing interaction.
• A shared FastAPI backend process for application APIs and domain modules, available for any server-side behavior the calculator requires.
• A MariaDB database provisioned as application-owned persistent storage.

The calculator's arithmetic is a self-contained, stateless interaction on a single page. The accepted requirements do not establish any durable actor-specific state, history, or commitment that must be stored or resumed, so the provisioned database does not by itself justify domain entities, authentication, or persistence of calculations. The backend and database remain part of the provisioned infrastructure inventory and are available for reuse; they do not add product requirements.

Actors

• Calculator User — the sole accepted active human persona. Anonymous, public, no account.
• Application (frontend/backend) — typed non-persona actor that renders the page and performs arithmetic.

Accepted behavior

• A simple calculator (explicit).
• Delivered as a single-page design (explicit).
• The design must be a single page (explicit hard constraint).
• The design must be a simple single-page calculator design (explicit hard constraint).

Ownership

• The single page Calculator is the anonymous public entry surface and the sole first-party owner of all accepted human-facing calculator behavior: number entry, operator selection, result display, and clearing.

Narrow exclusions

• No additional pages, routes, or destinations.
• No accounts, sign-in, or identity establishment.
• No persistence of calculations or history.
• No marketing headline, CTA, or onboarding flow.

Removed from scope

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

2a. Product Interpretation and Delivery Boundary

misty-start is delivered as exactly one page. That page is the anonymous public entry: it explains the product through its own presence — a single hard-edged instrument on empty paper — and hosts the entire calculator interaction. There is no separate landing page, no gate, and no protected area.

Access is public and anonymous. Because the accepted behavior is a stateless arithmetic interaction with no durable actor-specific state, no commitment, and no value transfer that must remain bound to a participant, no application-owned identity is established. Nothing in the product is protected.

The current horizon contains only the single-page calculator. No future features are accepted or planned in this document.

2c. Page Content and Component Coverage

Calculator

The one and only page. Anonymous public entry. It presents the product and hosts the complete calculator interaction.

Information and state

• Current expression (the sequence of entered numbers and operators), shown as a small tracked expression line in muted grey above the result.
• Current result, shown as oversized right-aligned tabular numerals.
• Active operator state, signalled by the accent colour on the selected operator key.
• Key press state, signalled by an instant ink-fill on the pressed key.

Primary actions

• Enter digits (0–9) and a decimal point.
• Select an operator (addition, subtraction, multiplication, division).
• Evaluate the expression via the equals key.
• Clear input to start a new calculation.

Supporting actions

• Correct input by clearing and re-entering.

Domain entities

• Expression (transient, in-page state only).
• Result (transient, in-page state only).
• No persisted entities.

Component responsibilities

• Wordmark block — small tracked uppercase wordmark "MISTY / CALCULATOR" flush left, with a single 2px rule beneath it.
• Metadata block — numbered metadata label flush right (e.g. "01 — ARITHMETIC"), tiny tracked caps.
• Display panel — ink-black panel at the top of the instrument; contains the muted expression line and the oversized right-aligned tabular result numeral, sized with clamp(40px, 9vw, 88px) so it never overflows.
• Keypad plate — a 4-column, 5-row key grid on surface #E7E4DC, hard-edged, divided by 1px ink hairlines, no shadow, no rounding. Contains digit keys, decimal point, operators, clear, and equals. The equals key is the only #E8382B cell.
• Colour-code legend — a five-swatch strip beneath the keypad (ink, grey, bone, red, ink) with tiny caps labels, acting as the page's palette key.
• Metadata strip — a sparse row of tiny tracked caps labels below the instrument.

States

• Loading — not applicable; the page is static and renders immediately.
• Empty — initial state: display shows a zero result and an empty expression line; no operator active.
• Success — a valid expression evaluates to a numeric result shown in the display; the expression line reflects the evaluated expression.
• Error — an invalid operation (for example division by zero) is surfaced in the display as an error indication rather than a numeric result; the user can clear to recover.
• Recovery — the clear key resets expression, result, and active operator to the empty state, allowing a new calculation.

3. Functional Requirements

FR-1 — Single-page calculator delivery (explicit) As a Calculator User, I should get a simple calculator delivered as a single page, so that I can do quick arithmetic without navigating anywhere.

• Trigger: the user opens the product.
• Observable result: the Calculator page renders as the sole page, containing the full calculator instrument.
• Access: anonymous, public.
• Failure/recovery: not applicable; the page is static.
• Continuation: the user proceeds to enter a calculation.

FR-2 — Single-page design constraint (explicit) As a Calculator User, I should experience the calculator as one simple single-page design, so that the experience stays focused and uncluttered.

• Constraint: the design must be a single page; no additional pages, routes, or destinations exist.
• Observable result: all calculator interaction occurs within the one page.
• Failure/recovery: not applicable.

FR-3 — Number entry (required_inference) As a Calculator User, I should enter digits and a decimal point, so that I can build the numbers I want to calculate.

• Trigger: the user presses a digit or decimal key.
• Observable result: the entered digits appear in the display and expression line.
• Access: anonymous, public.
• Failure/recovery: the clear key resets entry.
• Continuation: the user selects an operator or evaluates.

FR-4 — Operator selection (required_inference) As a Calculator User, I should select an arithmetic operator, so that I can combine numbers.

• Trigger: the user presses an operator key (addition, subtraction, multiplication, division).
• Observable result: the selected operator is recorded in the expression and signalled by the accent colour on the active operator key.
• Access: anonymous, public.
• Failure/recovery: the clear key resets the expression and active operator.
• Continuation: the user enters the next number.

FR-5 — Result evaluation (required_inference) As a Calculator User, I should evaluate my expression, so that I get an accurate result.

• Trigger: the user presses the equals key.
• Observable result: the computed result appears as oversized right-aligned tabular numerals in the display; the expression line shows the evaluated expression.
• Access: anonymous, public.
• Failure/recovery: an invalid operation (for example division by zero) is shown as an error indication in the display; the user clears to recover.
• Continuation: the user may continue calculating from the result or clear to start anew.

FR-6 — Clearing and correction (required_inference) As a Calculator User, I should clear my input, so that I can correct a mistake or start a new calculation.

• Trigger: the user presses the clear key.
• Observable result: expression, result, and active operator reset to the empty state.
• Access: anonymous, public.
• Failure/recovery: not applicable; clearing is itself the recovery path.
• Continuation: the user begins a new calculation.

4. User Personas

Calculator User

Product context. An anonymous visitor who needs to perform everyday arithmetic quickly. They arrive at the single page with no account, no prior state, and no expectation of onboarding. The page is the instrument.

Primary goal. Get an accurate arithmetic result without navigating away from the page.

Distinct accepted responsibilities.

• Enter numbers and operators.
• Read the running result.
• Clear or correct input to start a new calculation.

Relevant inputs or decisions. Which digits and operators to enter; when to evaluate; when to clear.

Interactions with other accepted participants. None beyond the application itself. The Calculator User is the sole human participant; the application renders the page and performs arithmetic.

Observable success. An accurate result appears in the display, and the user can clear and begin again without leaving the page.

5. Core User Flows

Flow 1 — Perform a calculation

1. The Calculator User opens the product. The Calculator page renders as the sole page, anonymous and public, showing the empty state: a zero result and an empty expression line.
2. The user presses digit keys to enter the first number. The digits appear in the display and expression line.
3. The user presses an operator key. The operator is recorded in the expression, and the active operator key is signalled in Saville red #E8382B.
4. The user presses digit keys to enter the second number.
5. The user presses the equals key — the only red cell in the keypad. The result cross-fades into the display over 120ms as oversized right-aligned tabular numerals; the expression line shows the evaluated expression.
6. The user reads the result. They may continue calculating from it or clear to start anew.

Failure/recovery. If the expression is invalid (for example division by zero), the display shows an error indication instead of a numeric result. The user presses the clear key to reset expression, result, and active operator to the empty state and begins again.

Flow 2 — Correct a mistake and start over

1. The Calculator User is mid-entry on the Calculator page.
2. The user presses the clear key.
3. Expression, result, and active operator reset to the empty state.
4. The user begins a new calculation from step 2 of Flow 1.

6. Visuals Colors and Theme

Muse and headline. Peter Saville — a quiet, gallery-hung instrument: monochrome silence, one centred artefact, sparse metadata blocks, and a single exact spot colour used as a code.

Palette (light mode)

No other hues anywhere. Red is a coded signal, never decoration.

Typography

• Headings: Archivo — neutral grotesque, set small and precise: wordmark and section labels in 500 weight, uppercase, tracked +0.18em at 11–12px.
• Body: Archivo.
• The result display is the only large type — 400 weight, tabular numerals, tight −0.02em tracking, right-aligned, sized by clamp so it never overflows.
• Scale: 1.25 modular on a small base — display numerals clamp(40px, 9vw, 88px); expression line 15px; wordmark 12px caps; key labels 20–22px; metadata labels 10px caps tracked; body 15px/1.55.

Shape language. Hard edges only — 0px radius on the keypad plate, display panel, and keys. Thin 1px ink hairlines divide keys, forming a visible grid. Keys are flat ink-on-bone or bone-on-ink rectangles with no shadow, no gradient, no rounding. A single 2px rule under the wordmark is the only ornament.

Layout. One centred column, max-width 420px, with vast silence around it. Above the instrument: a small tracked wordmark "MISTY / CALCULATOR" flush left with a numbered metadata block flush right (e.g. "01 — ARITHMETIC"). The instrument is a 4-column grid: a full-width display panel, then a 4×5 key grid where the equals key is the only red cell. Below, a sparse metadata strip of tiny caps labels. Everything flush-left ragged-right; asymmetric balance inside a symmetric frame.

Imagery. No photography, no illustration. The graphic artefact is the instrument itself plus one Saville-style reference detail: a thin colour-code band of five swatches (ink, grey, bone, red, ink) beneath the keypad acting as a legend, and hairline diagram rules. Typography and the grid are the image.

Accessibility. Readable text and controls stay whole at every viewport: wordmark, labels, numbers, and keys stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit. No other element covers any part of them.

7. Signature Design Concept

The public entry is a quiet, gallery-hung instrument. The viewport is bone-white paper (#F2F0EB), almost entirely empty. Dead centre sits a single hard-edged calculator plate, max 420px wide: an ink-black display panel at top with a huge right-aligned tabular numeral, and beneath it a hairline-ruled 4×5 key grid where exactly one cell — the equals key — is Saville red #E8382B. Above the plate, a tiny tracked wordmark left and a numbered metadata block right, like a record sleeve. Below, a five-swatch colour-code legend labelling ink / grey / bone / red as the page's palette key. No hero headline, no button, no gradient — the calculator is the artefact and the page's silence is the drama.

8. Interaction Model & Motion Direction

Interaction Model: Static (direction) Motion Tempo: still Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject. The calculator plate itself — the single hard-edged instrument centred on empty bone paper.
• Input → transformation → outcome thesis. A key press produces an instant 90ms ink-fill state change on the pressed key; the display's result cross-fades over 120ms when it updates. No entrance choreography, no bouncy feedback.
• Motion vocabulary. Instant ink-fill on key press; 120ms cross-fade on result update. Nothing else moves.
• Composed first frame. Bone-white paper, wordmark and numbered metadata block in the top corners, the calculator plate dead centre with a zero result in the display, the equals key the sole red cell, and the five-swatch legend beneath.
• Reduced-motion state. Under prefers-reduced-motion, the page is identical minus the cross-fade; key presses still give the instant ink-fill state change.

9. Non-Functional Requirements

NFR-1 — Single-page constraint (explicit) The design must be a single page. No additional pages, routes, or destinations may exist.

NFR-2 — Simplicity (explicit) The design must be a simple single-page calculator design. No onboarding, marketing gloss, or adjacent capability is accepted.

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

NFR-4 — Reduced motion (explicit, from creative direction) Under prefers-reduced-motion, the page is identical minus the result cross-fade; key presses still give the instant ink-fill state change.

NFR-5 — Palette discipline (explicit, from creative direction) No hues other than the specified palette. Saville red #E8382B is reserved exclusively for the equals key and the active operator. The generic indigo/blue-on-white SaaS template is forbidden.

NFR-6 — Anonymous public access (required_inference) The page is anonymous and public. No identity, sign-in, or protected area exists, because the accepted behavior is a stateless arithmetic interaction with no durable actor-specific state.

10. Tech Stack

• Frontend: React application UI.
• Backend: shared FastAPI process for application APIs and domain modules.
• Database: MariaDB for application-owned persistent data (provisioned; no domain entities are justified by the accepted calculator behavior).
• Containerization: Docker / docker-compose for the provisioned services (backend, database, frontend).

11. Assumptions and Constraints

• A-1 (explicit) The product is a simple calculator.
• A-2 (explicit) The calculator is delivered as a single-page design.
• A-3 (explicit) The design must be a single page.
• A-4 (explicit) The design must be a simple single-page calculator design.
• A-5 (required_inference) The calculator supports the four basic arithmetic operations (addition, subtraction, multiplication, division), digits, a decimal point, equals, and clear — the indispensable mechanics of a simple calculator.
• A-6 (required_inference) The page is anonymous and public; no identity is established because no durable actor-specific state, commitment, or value transfer requires it.
• A-7 (required_inference) Calculations are transient in-page state only; the provisioned database does not justify persistence of calculations.
• A-8 (explicit, from creative direction) The palette, typography, shape language, layout, motion, and imagery follow the supplied creative direction exactly.

12. Glossary

• Calculator User — the sole accepted active human persona; an anonymous visitor performing everyday arithmetic on the single page.
• Calculator — the one and only page; the anonymous public entry surface hosting the complete calculator interaction.
• Instrument — the calculator plate itself: display panel plus 4×5 key grid, centred on empty bone paper.
• Saville red — the exact spot colour #E8382B, reserved exclusively for the equals key and the active operator.
• Expression line — the small tracked muted-grey line above the result showing the entered expression.
• Keypad plate — the surface #E7E4DC 4-column, 5-row key grid, hard-edged and divided by 1px ink hairlines.
• Colour-code legend — the five-swatch strip (ink, grey, bone, red, ink) beneath the keypad acting as the page's palette key.
• Empty state — the initial state: zero result, empty expression line, no active operator.