System Requirements Document for sky-start

1. Introduction

sky-start is a simple calculator delivered as a single page. The product intent is narrow and complete: a person opens one page, enters numbers and operations, and reads the arithmetic result. There is no account, no saved history, no multi-page navigation, and no surrounding application shell beyond the calculator itself.

The audience is everyday users who need quick, light arithmetic in a browser. The experience should feel quick and confident rather than corporate: one screen that reads like a small brand, not a template.

This document is the System Requirements Document for sky-start. It specifies the calculator's behavior, its single page, its visual and motion direction, and the technical delivery boundary.

Success Criteria

• A user can open the single Calculator page and complete an arithmetic calculation without any sign-in, setup, or navigation.
• The result of each calculation is displayed prominently and legibly at 375px, 768px, and 1280px viewport widths.
• The page presents exactly one destination: the Calculator. No additional pages, routes, or navigation surfaces exist.
• The visual presentation follows the supplied creative direction (hot pink ground, cream display panel, lime active-operator and equals keys, Archivo Black display numerals) rather than a generic template look.

2. System Overview

sky-start is a one-page web calculator. The single page, Calculator, is the anonymous public entry and the entire product surface. A user types digits, chooses an operator, and evaluates an expression; the page shows the running entry and the result.

Current delivery consists of:

• Frontend (React): renders the Calculator page — the display panel, the keypad, the operator state, and the result.
• Backend (shared FastAPI process): hosts application APIs and domain modules. For the current calculator scope, arithmetic is performed in the browser on the page; the backend exists as the shared application process and is available for any server-side domain module the product later requires. It does not add product behavior on its own.
• Database (MariaDB): provisioned application-owned storage. The current calculator scope has no durable domain entities, no saved history, and no accounts, so no product data is persisted. The database is provisioned infrastructure only.

Actors:

• Calculator user (active human persona): opens the Calculator page, enters numbers and operations, and reads the result.
• Application (system actor): the React frontend and shared FastAPI backend that render the page and execute arithmetic.

Narrow exclusions: no authentication, no user accounts, no saved calculation history, no sharing, no multi-page navigation, no settings, no unit conversion, no scientific or programmer modes beyond the arithmetic operations specified in Section 3.

Removed from scope

• None. No concept was explicitly removed by the user; the scope was narrowed to a simple single-page calculator from the outset.

2a. Product Interpretation and Delivery Boundary

sky-start is delivered as a first-party, single-page web application. The Calculator page is publicly reachable with no identity requirement: a visitor lands on the page and immediately has the full calculator. There is no anonymous pre-identity lifecycle, because no protected state, durable relationship, or commitment exists that would require identity continuity. Nothing is saved between visits, so there is no returning-user verification and no account management.

The page owns the entire accepted lifecycle: entry of operands, selection of an operator, evaluation, display of the result, and recovery from invalid input. The backend and database are provisioned infrastructure that support the application process; they do not introduce additional user-facing destinations or product capabilities in the current scope.

Future work is explicitly out of the current boundary and is listed in Section 11 only as a labeled future horizon; it is not part of current pages or acceptance.

2c. Page Content and Component Coverage

Calculator

The single page of the product. It is the anonymous public entry and the complete working surface.

Information and state

• Current entry string (the digits and decimal point the user has typed).
• Pending operator (one of +, −, ×, ÷) and the stored first operand.
• Displayed value: the current entry while typing, or the result after evaluation.
• Active-operator state: which operator key, if any, is currently selected.
• Error state: an invalid expression (for example division by zero) or malformed entry.

Primary actions

• Digit keys 0–9 append a digit to the current entry.
• Decimal point key appends a decimal point, at most once per entry.
• Operator keys +, −, ×, ÷ select the pending operator and store the current entry as the first operand.
• Equals key evaluates the pending expression and displays the result.
• Clear key resets the entry, pending operator, stored operand, and error state to the initial state.

Supporting actions

• Backspace/delete removes the last character of the current entry (supporting correction of a mistyped digit).

Domain entities

• Calculation: an in-memory expression consisting of a first operand, an operator, a second operand, and a result. It is not persisted.

Component responsibilities

• Display panel: cream surface holding the current value or result in large Archivo Black tabular numerals; shows the pending expression context (operator and first operand) in a smaller line above the main value.
• Keypad: 4-column grid of 72px keys with hard 6px black offset shadows; digits and decimal on cream keys with black text; operator keys flip to lime when active; equals key is lime.
• Sticker badge: rotated "SKY-START" badge at the top corner, decorative only.
• Decorative blob: a small flat/glossy 3D-style blob beside the display, decorative only and never covering readable text or controls.

States

• Loading: not applicable in a meaningful way; the page renders immediately with an initial display of 0.
• Empty: initial state shows 0 on the display with no pending operator.
• Success: after equals, the result appears on the display with a short spring scale-in; the result becomes the current entry for chained calculations.
• Error: division by zero or an invalid expression shows a clear error message on the display (for example "Cannot divide by zero"); the next digit or Clear recovers to a usable state.
• Recovery: Clear always returns the page to the initial 0 state; Backspace corrects a mistyped entry without a full reset.

3. Functional Requirements

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

• Provenance: explicit (single page design of calculator).
• Trigger: navigating to the application root.
• Observable result: the Calculator page renders with the display showing 0 and the full keypad visible.
• Access: anonymous public entry; no identity required.
• Failure/recovery: if the page fails to load, reloading the page restores the initial state.
• Continuation: the user proceeds to enter digits.

FR-2 — Enter digits As a Calculator user, I should press digit keys to build a number on the display, so that I can enter an operand.

• Provenance: explicit (calculator).
• Trigger: pressing a digit key 0–9.
• Observable result: the digit is appended to the current entry and shown on the display; a leading 0 is replaced by the first non-zero digit.
• Access: anonymous.
• Failure/recovery: Backspace removes the last digit; Clear resets to 0.
• Continuation: the user continues entering digits or selects an operator.

FR-3 — Enter a decimal point As a Calculator user, I should press the decimal point key to enter a fractional number, so that I can calculate with decimals.

• Provenance: explicit (calculator).
• Trigger: pressing the decimal point key.
• Observable result: a decimal point is appended to the current entry; pressing it again in the same entry has no additional effect.
• Access: anonymous.
• Failure/recovery: Backspace removes the decimal point; Clear resets.
• Continuation: the user continues entering digits.

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 the next operand.

• Provenance: explicit (calculator).
• Trigger: pressing an operator key.
• Observable result: the current entry is stored as the first operand, the operator becomes pending, and the operator key flips to lime to mark it active.
• Access: anonymous.
• Failure/recovery: pressing a different operator replaces the pending operator; Clear resets.
• Continuation: the user enters the second operand.

FR-5 — Evaluate an expression As a Calculator user, I should press the equals key to compute the result, so that I can see the answer.

• Provenance: explicit (calculator).
• Trigger: pressing the equals key with a first operand, a pending operator, and a second operand.
• Observable result: the arithmetic result is displayed on the display panel with a short spring scale-in; the result becomes the current entry for chained calculations.
• Access: anonymous.
• Failure/recovery: if no second operand has been entered, equals uses the current entry as the second operand; if the expression is invalid, see FR-6.
• Continuation: the user can chain another operator onto the result or press Clear to start over.

FR-6 — Handle invalid operations As a Calculator user, I should see a clear message when an operation is invalid, so that I understand why no result appeared and can recover.

• Provenance: required_inference (indispensable failure/recovery for division by zero and malformed expressions).
• Trigger: pressing equals on an expression that cannot be evaluated (for example division by zero).
• Observable result: the display shows an error message instead of a number.
• Access: anonymous.
• Failure/recovery: pressing a digit or Clear returns the calculator to a usable state.
• Continuation: the user corrects the input and evaluates again.

FR-7 — Clear the calculator As a Calculator user, I should press the clear key to reset the calculator, so that I can start a new calculation.

• Provenance: explicit (calculator).
• Trigger: pressing the clear key.
• Observable result: the display returns to 0, the pending operator is cleared, the stored operand is discarded, and any error state is removed.
• Access: anonymous.
• Failure/recovery: not applicable; Clear always succeeds.
• Continuation: the user begins a new calculation.

FR-8 — Correct a mistyped entry As a Calculator user, I should press the backspace key to remove the last character, so that I can fix a mistake without clearing everything.

• Provenance: required_inference (indispensable correction mechanic for digit entry).
• Trigger: pressing the backspace key while an entry is present.
• Observable result: the last character of the current entry is removed; if the entry becomes empty, the display shows 0.
• Access: anonymous.
• Failure/recovery: not applicable.
• Continuation: the user continues entering digits.

4. User Personas

Calculator user

Product context. An everyday person who needs to do a quick calculation in a browser — a total, a split, a percentage-free sum — and wants the answer immediately without signing in, installing anything, or navigating a menu.

Primary goal. Enter a number, choose an operation, enter another number, and read the result in as few taps as possible.

Distinct accepted responsibilities.

• Enters digits and decimal points to build operands.
• Selects the operator that matches the intended arithmetic.
• Commits the calculation by pressing equals.
• Reads the result and decides whether to chain another operation or clear and start over.
• Corrects mistakes with backspace or clear.

Relevant inputs and decisions. Which operator to use; whether the displayed value is the entry or the result; whether to chain or reset after a result; how to recover from an error message.

Interactions with other accepted participants. The Calculator user is the only active human persona. The application (frontend and backend) renders the page and executes arithmetic; the user interacts with it directly and receives the result on the display.

Observable success. The correct arithmetic result appears on the display panel, legibly, at the user's viewport width, and the user can immediately start another calculation.

5. Core User Flows

Flow 1 — Perform a basic calculation

1. The Calculator user opens the application root in a browser. The Calculator page renders with the display showing 0 and the full keypad visible. No sign-in is required.
2. The user presses digit keys to enter the first operand. Each digit appends to the display.
3. The user presses an operator key (for example ×). The current entry is stored as the first operand, the operator becomes pending, and the operator key flips to lime.
4. The user presses digit keys to enter the second operand. The display shows the second operand.
5. The user presses the equals key. The application computes the result and the display shows it with a short spring scale-in.
6. The user reads the result. They may press an operator to chain another calculation onto the result, or press Clear to return to 0.

Failure/recovery. If the user mistypes a digit, they press backspace to remove it and continue. If they want to abandon the calculation, they press Clear and the page returns to the initial 0 state.

Flow 2 — Recover from an invalid operation

1. The Calculator user enters a first operand, selects ÷, and enters 0 as the second operand.
2. The user presses equals. The application cannot evaluate the expression and the display shows an error message instead of a number.
3. The user presses a digit or Clear. The calculator returns to a usable state — the digit begins a fresh entry, or Clear resets to 0.
4. The user enters a valid expression and presses equals to obtain the result.

Flow 3 — Correct a mistyped entry

1. The Calculator user is entering a number and presses a wrong digit.
2. The user presses backspace. The last character is removed from the display.
3. The user continues entering the correct digits and proceeds with the calculation as in Flow 1.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. Muse: Jessica Walsh. Headline idea: a one-screen calculator that feels like a small brand — saturated colour, chunky type, confident and light.

Mode: light mode only.

Colour tokens (exact hex by role)

Typography

• Headings and display numerals: Archivo Black, extra-bold uppercase, tight leading, tabular figures for numerals.
• Body and key labels: Unbounded.
• Type scale: 1.5 modular — 96 / 64 / 40 / 24 / 18 px.
• Display numeral size: clamp(56px, 12vw, 128px).

Shape language

• Thick rounded keys with hard 6px black offset shadows.
• Sticker-like badges and capsule chips.
• No thin hairline borders.

Layout

• One column.
• A giant result display sits in the top half on a cream panel.
• A 4-column keypad fills the lower half with 72px keys.
• A rotated "SKY-START" sticker badge sits at the top corner.
• A small flat/glossy 3D-style blob sits beside the display as decoration only.

Imagery style

• No photographs. Flat sticker shapes and a small glossy blob as decoration only; decoration never covers readable text or controls.

Accessibility and fit

• Readable text and controls stay whole at 375px, 768px, and 1280px, wrapping or scaling to fit; no element covers any part of them.
• With prefers-reduced-motion, the page presents a usable static arrangement with all keys and the display fully visible.

Avoid

• White or near-white page ground.
• Blue or indigo accents.
• Identical hover-lift card grids.
• Gradient blob heroes.
• Thin hairline borders.

7. Signature Design Concept

The first screen is the calculator. A full-bleed hot pink (#FF4FA3) ground fills the viewport. Centered in the top half sits a cream (#FFF4E4) display panel carrying a 128px Archivo Black black (#141414) result number with tabular figures. A rotated "SKY-START" sticker badge anchors the top corner, and a small glossy blob sits beside the display as decoration.

The lower half is a 4-column keypad of 72px cream keys with black digits, each carrying a hard 6px black offset shadow. The lime (#C6F24E) equals key is the only bright control at rest; when an operator is selected, that operator key flips to lime, so the page's colour tells the user exactly which operation is pending.

The signature move is the contrast between the saturated pink field and the cream panel: the display reads like a printed label on a bold poster, and the keypad reads like physical chunky keys. Nothing else competes for attention.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the cream display panel with the large black result numeral, set on the hot pink ground.
• Input → transformation → outcome thesis: a key press (input) depresses the key 4px and collapses its offset shadow (transformation), and the display updates — digits appear as typed, an operator key flips to lime in a 120ms colour swap, and the result scales in with a short spring (outcome).
• Motion vocabulary: 4px key press-down with shadow collapse; 120ms colour swap on operator selection; short spring scale-in on result digits.
• Composed first frame: hot pink ground, cream display panel showing 0 at 128px Archivo Black, rotated "SKY-START" sticker badge at the top corner, glossy blob beside the display, 4-column keypad below with the lime equals key as the only bright control.
• Reduced-motion state: with prefers-reduced-motion, key presses and result updates occur without the press-down, colour-swap, or spring animation; the page presents a static, fully usable arrangement with all keys and the display visible.

9. Non-Functional Requirements

• NFR-1 — Single page. The product presents exactly one page, the Calculator. No additional routes, navigation, or pages exist. (Provenance: explicit — "simple single page design of calculator".)
• NFR-2 — Simplicity. The design is simple: one display, one keypad, no surrounding application shell. (Provenance: explicit — "The design is simple.")
• NFR-3 — Responsive legibility. Readable text and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit; no element covers any part of them. (Provenance: explicit — creative direction readability rule.)
• NFR-4 — Reduced motion. With prefers-reduced-motion, the page provides a usable static arrangement. (Provenance: explicit — creative direction.)
• NFR-5 — No identity requirement. The Calculator page is anonymously reachable; no authentication, accounts, or sessions are required. (Provenance: required_inference from the absence of any protected state or durable relationship.)
• NFR-6 — No persistence of calculations. Calculations are in-memory only; no history is stored. (Provenance: required_inference from the absence of any accepted history capability.)
• NFR-7 — Immediate render. The page renders its initial 0 state without a blocking loading state. (Provenance: required_inference for a usable calculator entry.)

10. Tech Stack

• Frontend: React application UI rendering the single Calculator page.
• Backend: shared FastAPI process hosting application APIs and domain modules.
• Database: MariaDB, provisioned application-owned storage. The current calculator scope persists no product data; the database is infrastructure only.
• Containerization: Docker / docker-compose for the backend, database, and frontend services.

No additional services are required for the current calculator scope.

11. Assumptions and Constraints

Assumptions

• Arithmetic is performed in the browser on the Calculator page; the backend is available for future server-side domain modules but is not required for the current arithmetic.
• The calculator supports the four basic operations (+, −, ×, ÷), decimal entry, clear, and backspace. No scientific, programmer, or memory functions are in scope.
• The page is light mode only, per the creative direction.

Constraints

• The design is simple and uses a single page (explicit).
• The product is a simple calculator (explicit).
• The visual presentation follows the supplied creative direction: hot pink ground, cream display panel, lime active-operator and equals keys, Archivo Black display numerals, Unbounded body, hard offset shadows, no thin borders, no white ground, no blue/indigo accents.
• Readable text and controls stay whole at 375px, 768px, and 1280px.

Future horizon (not current scope, not acceptance criteria)

• Saved calculation history, user accounts, and additional calculator modes are not part of the current product and are not implemented in the current pages.

12. Glossary

• Calculator page: the single page of sky-start; the anonymous public entry and the complete working surface.
• Display panel: the cream surface at the top of the page showing the current entry or result.
• Keypad: the 4-column grid of 72px keys below the display.
• Pending operator: the operator selected by the user, awaiting the second operand and evaluation.
• First operand: the number stored when an operator is selected.
• Second operand: the number entered after an operator is selected.
• Chained calculation: using a displayed result as the first operand of a subsequent operation.
• Active-operator state: the visual state in which the selected operator key is lime.
• Sticker badge: the rotated "SKY-START" decorative badge at the top corner.
• Glossy blob: the small decorative 3D-style shape beside the display.