System Requirements Document for kinetic-start

1. Introduction

kinetic-start is a project to build a simple calculator delivered as a single-page design. The product intent is narrow and explicit: one page that presents a working everyday calculator — number and operator entry, a computed result, and clearing — with no navigation away from that page. The audience is anyone who needs quick, accurate arithmetic and wants the tool itself to disappear behind the operation.

The design brief frames the calculator as a Braun instrument in the spirit of Dieter Rams: honest controls, a strict grid, muted warm surfaces, and a single saturated signal colour used only where the machine is speaking. The numbers are the content; decoration is excluded.

Success Criteria

• A visitor can open the single page and complete an arithmetic calculation (enter numbers and operators, see the result) without navigating to any other page.
• The result readout is legible and whole at 375px, 768px, and 1280px viewports.
• The equals key and the currently active operator are the only elements rendered in the Braun orange signal colour, so machine state is readable from colour alone.
• Clearing returns the calculator to a fresh, usable state from the same page.

2. System Overview

2a. Product Interpretation and Delivery Boundary

The product is a single-page calculator. There is exactly one page — Calculator — and it is the anonymous public entry: no account, no sign-in, and no identity establishment is required or provided. All accepted behavior (number entry, operator selection, result computation, clearing) happens on that one page.

Delivery is a first-party custom UI: a React frontend served to the browser, backed by the shared FastAPI backend process and a MariaDB database provisioned in the scaffold. The calculator's arithmetic is a client-side interaction on the single page; the backend and database are provisioned infrastructure and do not, by themselves, create product requirements, stored domain entities, or authentication. No future features are currently specified.

2b. Source Content Inventory

Not applicable — no reference directive with content_source was supplied.

2c. Page Content and Component Coverage

Calculator

The single page of the product, presented as a Braun-style instrument on a warm off-white workbench ground.

Information and state

• Wordmark "KINETIC START" top-left in 11px small-caps, with a 1px full-viewport-width rule beneath the top bar and a tiny "CALC / 001" model number at the right of that bar.
• Oversized tabular result readout, clamp(56px, 9vw, 120px), never wrapping.
• Running expression line in 11px small-caps above the readout.
• A small-caps label/value metadata row above the keypad showing "EXPRESSION" and "RESULT" as aligned columns, echoing a technical spec plate.
• Active operator state: the currently selected operator key renders in Braun orange (#D94E1F).
• Calculator state: current entry, pending operator, running expression, computed result, cleared/fresh state.

Primary actions

• Enter digits (0–9) and a decimal point.
• Select operators: plus, minus, multiply, divide.
• Press equals to compute and display the result.
• Clear (memory/clear row) to reset the calculation and start over.

Supporting actions

• Correct the current entry before committing an operator (via clear).
• Continue calculating from a displayed result by selecting a new operator.

Domain entities

• Calculation expression (the sequence of entered operands and operators).
• Current operand entry.
• Pending operator.
• Result value.
• These are in-page interaction state; no persistent stored entity is required by the accepted source.

Component responsibilities

• Top bar: wordmark, full-width hairline rule, model number label.
• Readout block: expression line (small-caps metadata), oversized tabular result, 12-column grid guide rule at 4% opacity behind the readout.
• Spec-plate metadata row: aligned "EXPRESSION" / "RESULT" label-value pairs.
• Keypad: 4×5 grid of flat rounded-rectangle keys (10px radius, 6px gap), each with a 1px bottom lip and 1px inset top highlight; digits, decimal, operators, equals (orange), clear row (mustard #F2B705).
• Pictogram row: plus, minus, multiply, divide as thick 2px-line geometric glyphs.

States

• Loading: not applicable — the page is a static client-rendered calculator with no remote data fetch required for its core interaction.
• Empty/fresh: readout shows a zero/initial state; expression line empty; no operator active.
• Success: result displayed in the oversized readout; expression line shows the running expression.
• Error: division by zero or an invalid expression shows an error indication in the readout rather than a numeric result; clear returns to the fresh state.
• Recovery: clear resets all state to fresh; entering a new digit after an error begins a new entry.

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 perform arithmetic without navigating anywhere else.

• Trigger: opening the product.
• Observable result: the Calculator page loads with the readout and keypad visible.
• Constraint: exactly one page; no additional destinations.
• Failure/recovery: not applicable to page load beyond standard browser behavior.

FR-2 — Number entry (required_inference) As a Calculator User, I should enter digits and a decimal point, so that I can build the operands of my calculation.

• Input: digit keys 0–9 and decimal point.
• Observable result: the entered number appears in the readout and in the running expression.
• Continuation: further digits append to the current entry.

FR-3 — Operator selection (required_inference) As a Calculator User, I should select plus, minus, multiply, or divide, so that I can specify the operation.

• Input: operator key press.
• Observable result: the selected operator becomes the active operator and is rendered in Braun orange; the expression line records the operator.
• Continuation: the next digit entry begins the second operand.

FR-4 — Compute result (required_inference) As a Calculator User, I should press equals, so that I can see the computed result of my expression.

• Input: equals key press.
• Observable result: the result appears in the oversized tabular readout; the expression line shows the completed expression.
• Failure/recovery: division by zero or an invalid expression shows an error state in the readout; clear recovers to fresh.
• Continuation: selecting a new operator continues calculating from the displayed result.

FR-5 — Clear and start over (required_inference) As a Calculator User, I should clear the calculation, so that I can correct a mistake or begin a new calculation.

• Input: clear key press.
• Observable result: readout returns to the fresh state, expression line empties, no operator is active.
• Continuation: the user can immediately enter a new calculation.

FR-6 — Legible, whole controls at all viewports (explicit — design constraint) As a Calculator User, I should see the wordmark, labels, numbers, and every key fully inside the viewport and their container at 375px, 768px, and 1280px, so that I can read and press everything without clipping.

• Observable result: no readable text or control is cropped or covered at any of the three viewports; the readout scales via clamp() and never wraps.

4. User Personas

Calculator User

Product context. An everyday person who needs quick, accurate arithmetic and opens the single Calculator page to do it. They are not signing in, not managing anything, and not navigating — the page is the tool.

Primary goal. Get an accurate result from an arithmetic expression with minimal friction, on a page whose controls are honest and whose numbers are the content.

Distinct accepted responsibilities.

• Entering digits and a decimal point to build operands.
• Selecting an operator (plus, minus, multiply, divide), which becomes the active operator shown in orange.
• Pressing equals to compute and read the result.
• Clearing to correct a mistake or start a new calculation.

Relevant inputs or decisions. Which digits to enter, which operator applies, when to press equals, and when to clear. The user reads machine state from colour (orange equals and active operator) and from the expression line.

Interactions with other accepted participants. None — the calculator is a single-user, single-page tool with no counterparty, recipient, or shared state.

Observable success. The result appears in the oversized tabular readout, the expression line reflects what was entered, and the user can continue or clear without leaving the page.

5. Core User Flows

Flow 1 — Perform a calculation

1. Start: The Calculator User opens the single Calculator page. The page shows the wordmark, the readout in its fresh state, the expression line, and the keypad.
2. Enter first operand: The user presses digit keys (and a decimal point if needed). The digits appear in the readout and the expression line.
3. Select operator: The user presses an operator key. That key becomes the active operator and renders in Braun orange; the expression line records the operator.
4. Enter second operand: The user presses digit keys for the second operand; they appear in the readout.
5. Compute: The user presses the orange equals key. The result appears in the oversized tabular readout and the expression line shows the completed expression.
6. Continue or finish: The user may select a new operator to continue from the result, or clear to start over. The user remains on the same page throughout.

Failure/recovery: If the expression is invalid (for example, division by zero), the readout shows an error indication instead of a number. The user presses clear, the page returns to the fresh state, and they begin a new calculation.

Flow 2 — Correct a mistake and start over

1. Start: The Calculator User is mid-calculation on the Calculator page and notices an incorrect entry.
2. Clear: The user presses the clear key (mustard memory/clear row). The readout returns to the fresh state, the expression line empties, and no operator is active.
3. Restart: The user enters a new calculation following Flow 1, without leaving the page.

6. Visuals Colors and Theme

The creative direction is authoritative for this section.

Muse and headline. Dieter Rams — "Less, but better: a calculator as a Braun instrument."

Colour tokens (light mode)

• Background: #EFEBE4 (warm off-white ground)
• Surface: #E3DED4 (calculator body, slightly deeper warm grey)
• Text: #1A1A18 (near-black ink for all numerals and labels)
• Primary / signal: #D94E1F (Braun orange — reserved exclusively for the equals key and the active operator)
• Accent: #F2B705 (mustard — memory/clear row only)
• Muted: #8C877C (secondary labels, hairline rules)
• Rules: 1px #1A1A18 at 12% opacity
• No other colours. No blue or indigo anywhere.

Typography

• Headings: Archivo, medium weight, tight tracking (-0.02em), sentence case for the wordmark, small-caps for every control and section label at 11px with +0.12em letterspacing. No display weights above 700.
• Body: Archivo.
• Scale (1.25 modular): wordmark 20/18/16; display numerals clamp(56px, 9vw, 120px) tabular; operator keys 22/20/18; labels 11px small-caps; helper copy 14/14/13. All numerals tabular-lining.

Shape language

• Keys: rounded rectangles, 10px radius, 6px gap, flat, with a 1px bottom edge reading as a physical button lip and a 1px inset top highlight.
• Calculator body: a single 18px-radius slab with a 1px hairline border and a 2px inset top highlight.
• No shadows beyond a single 0 1px 0 rgba(0,0,0,0.06) contact line.

Layout

• Desktop (1280px): two-column asymmetric grid — left column 5 of 12 holds the oversized result readout and the running expression line as small-caps metadata; right column 6 of 12 holds the 4×5 keypad on the warm surface.
• 768px: columns stack with the readout above.
• 375px: single column — readout, expression line, then the keypad filling the width with 4 equal columns and 6px gaps.
• Everything aligned to an 8pt baseline grid; label/value pairs flush left with a 12px gutter.

Imagery. No photography. The instrument itself is the imagery: the keypad as a diagrammatic object, hairline rules, small-caps metadata labels, and a tiny pictogram row (plus, minus, multiply, divide) as thick 2px-line geometric glyphs. A faint 12-column grid guide may appear as a 1px rule behind the readout at 4% opacity.

7. Signature Design Concept

The first screen is the calculator, presented like a Braun product on a workbench. The warm off-white page (#EFEBE4) holds a single 18px-radius calculator slab offset slightly right of centre, with an oversized tabular result (clamp(56px, 9vw, 120px)) bleeding to the left edge of the slab and the expression line in small-caps beneath it. The wordmark "KINETIC START" sits top-left in 11px small-caps with a 1px rule running the full viewport width beneath it, and a tiny "CALC / 001" model number at the right. There is no centred headline, no subtext block, and no button stack: the keypad is the hero, with the orange equals key as the only saturated element on the page.

Signature moves carried into implementation:

• Oversized tabular result readout that grows to fill the left column and never wraps, with the running expression in 11px small-caps above it.
• A 1px full-viewport-width rule under the top bar with the wordmark left and the model number right, like a Braun product label.
• Keys built as physical buttons: 1px bottom lip, 1px inset top highlight, and a 1px depression on :active with a 90ms release, no shadow lift.
• Braun orange reserved exclusively for the equals key and the currently active operator, so machine state is readable from colour alone.
• A small-caps label/value row above the keypad showing "EXPRESSION" and "RESULT" as aligned metadata columns, echoing a technical spec plate.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the calculator slab itself — the keypad as a diagrammatic object with the oversized tabular result readout.
• Input → transformation → outcome thesis: a key press depresses the key 1px and darkens it on :active with a 0ms delay and a 90ms release; the result readout updates without transition, with a 120ms opacity crossfade only when the value changes length. The outcome is the machine's state made visible — the active operator and equals key in orange, the result in the oversized readout.
• Motion vocabulary: instant, mechanical feedback. No entrance animation, no bounce, no particles, no glows, no decorative animation.
• Composed first frame: warm off-white ground; wordmark top-left with the full-width hairline rule and "CALC / 001" at right; the calculator slab offset slightly right of centre; the oversized tabular result bleeding to the left edge of the slab; the expression line in small-caps beneath it; the keypad with the orange equals key as the only saturated element.
• Reduced-motion state: identical, minus the readout crossfade. Keys still depress and darken on :active; the result still updates instantly.

9. Non-Functional Requirements

• Single-page constraint (explicit): the product is exactly one page; no additional routes, destinations, or navigation.
• Viewport legibility (explicit — design constraint): readable text and controls stay whole at 375px, 768px, and 1280px; the readout scales via clamp() and never wraps; no element covers any part of a label, number, or control.
• Accessibility of motion (explicit — design constraint): with prefers-reduced-motion, the page provides the identical usable static arrangement minus the readout crossfade.
• Colour discipline (explicit — design constraint): no blue or indigo accents; no more than two accent colours on the page at once (Braun orange and mustard, each reserved to its stated role).
• No authentication (explicit — access contract): the Calculator page is an anonymous public entry; no account, sign-in, or identity establishment is required or provided.
• Performance (basic_default): the calculator's arithmetic is a client-side interaction; the page should render and respond to key presses without perceptible delay.

10. Tech Stack

• Frontend: React application UI (single-page calculator).
• Backend: shared FastAPI process for application APIs and domain modules (provisioned scaffold; the calculator's core interaction is client-side and does not require a backend call).
• Database: MariaDB for application-owned persistent data (provisioned scaffold; no persistent calculator entity is required by the accepted source).
• Infrastructure: docker-compose with the backend, database, and frontend services as listed in the initial scaffold inventory.

11. Assumptions and Constraints

• Assumption (required_inference): the calculator supports the four basic operations (plus, minus, multiply, divide), digits 0–9, a decimal point, equals, and clear, as implied by the accepted single-page calculator requirement and the creative direction's keypad and pictogram row.
• Assumption (required_inference): division by zero or an invalid expression produces an error indication in the readout rather than a numeric result, recoverable via clear.
• Constraint (explicit): the design must be a simple single page — exactly one page, no navigation.
• Constraint (explicit): the Calculator page is anonymous; no authentication or account management is in scope.
• Constraint (explicit — design): 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 — design): no photography, gradients, glassmorphism, floating cards, drop shadows, glows, or decorative animation.
• Out of scope: scientific functions, history, memory storage beyond the clear row, unit conversion, and any multi-page navigation — none are specified by the authoritative source.

12. Glossary

• Calculator page — the single page of the product; the anonymous public entry hosting the readout, expression line, and keypad.
• Readout — the oversized tabular display of the current entry or computed result.
• Expression line — the small-caps metadata line showing the running expression above the readout.
• Active operator — the currently selected operator key, rendered in Braun orange.
• Signal colour — Braun orange #D94E1F, reserved for the equals key and the active operator.
• Spec plate — the small-caps "EXPRESSION" / "RESULT" label-value metadata row above the keypad.
• Fresh state — the cleared calculator state with an empty expression and no active operator.