System Requirements Document for venus-calculator

1. Introduction

venus-calculator is a simple, single-page calculator design. The product intent is to present one calculator page where a person can enter numbers and arithmetic operations and see the computed result displayed. The design must be simple and must be contained on a single page.

The audience is the anonymous person who opens the calculator page to perform quick arithmetic. The experience is treated as a crafted instrument rather than a utility screen: the numbers themselves are the living material, presented within a quiet, art-institution-grade visual atmosphere.

2. System Overview

venus-calculator is delivered as a single custom page, Calculator, which is the anonymous public entry surface. There is no account, sign-in, or identity establishment: the page is openly reachable and the calculator is immediately usable.

The single active human actor is the Calculator User, who opens the page, enters digits and operations, and reads the displayed computed result. All arithmetic entry and result display are owned by the Calculator page itself.

The current delivery is limited to the simple single-page calculator design. No additional pages, navigation destinations, saved history, accounts, or adjacent capabilities are part of the current scope.

2a. Product Interpretation and Delivery Boundary

The product is one page. The Calculator page is the anonymous public entry and the only destination. It owns number entry, operation entry, and the displayed computed result. Access requires no identity: the page is open to any visitor, and no protected state exists behind it.

The design constraint is explicit and binding: the design must be simple, and it must be a single page. The visual direction (a generative particle field behind a floating calculator panel) is atmosphere and decoration layered behind the calculator; it does not create a second page, a second destination, or any additional product capability. The particle field is seeded by the digits on screen and responds to arithmetic, but the only product behavior remains arithmetic entry and displayed results.

Future ideas are not part of current scope and are not represented on the page.

2c. Page Content and Component Coverage

Calculator

The Calculator page is the single, anonymous public entry surface. It presents the calculator and owns all number and operation entry with displayed computed results.

Information and state

• Wordmark: small uppercase label "VENUS / CALCULATOR" flush-left within the panel column, with a one-line caption beneath it.
• Running expression: the current expression shown in muted slate above the numeric display.
• Numeric display: the current entry or result, oversized tabular numerals in warm off-white.
• Result line: the computed result shown in amber beneath the display.
• Keypad: a 4-column grid of keys in graphite with hairline borders; the equals key is a full-width amber capsule.
• Particle field: a full-bleed generative background canvas seeded by the digits on screen; it brightens and shifts hue toward teal when a result is computed.

Primary actions

• Enter digits (0–9) and a decimal point.
• Select an arithmetic operation (add, subtract, multiply, divide).
• Evaluate the expression with the equals key.
• Clear the current entry and reset the calculation.

Supporting actions

• Read the running expression and the result line.
• Observe the particle field responding to the entered digits and to a computed result.

Domain entities

• Expression: the sequence of entered operands and operators.
• Operand: a numeric value entered by the user.
• Operator: an arithmetic operation selected by the user.
• Result: the computed numeric outcome of the expression.

Component responsibilities

• Display component: renders the running expression, the numeric display, and the result line; cross-fades digits on update.
• Keypad component: renders digit keys, operator keys, decimal key, clear key, and the equals capsule; reports key presses.
• Calculation logic: evaluates the entered expression and produces the result.
• Particle field component: renders the generative background seeded by the digits on screen and shifts hue toward teal for 800ms on result.

States

• Loading: the page and particle field initialize; the calculator panel is presented with an empty display.
• Empty: no digits entered; the display shows an initial zero state and the expression area is blank.
• Success: digits and operators entered; on equals, the result appears in the amber result line and the display cross-fades to the result.
• Error: an invalid or incomplete expression (for example, an operator with no following operand, or division by zero) does not produce a result; the display retains the last valid entry so the user can correct it.
• Recovery: the clear key resets the entry and expression so the user can begin again.
• Reduced motion: the particle field freezes into a static render and key-press scaling is removed; all calculator controls remain fully usable.

3. Functional Requirements

FR-1 — Single-page calculator presentation (explicit) As a Calculator User, I should see the calculator presented on one page, so that I can perform arithmetic in one place.

• Trigger: the user opens the page.
• Observable result: the Calculator page renders with the numeric display and keypad visible.
• Access: anonymous, no identity required.
• Failure/recovery: if the page fails to initialize, reloading the page restores the calculator.
• Continuation: the user proceeds to enter digits.

FR-2 — Simple design (explicit) As a Calculator User, I should experience a simple design, so that the calculator is immediately understandable and usable.

• Observable result: the page presents the calculator without extraneous product surfaces or navigation.
• Continuation: the user can locate the display and keypad at once.

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

• Trigger: the user presses a digit or decimal key.
• Observable result: the entered digits appear in the numeric display and the running expression.
• Failure/recovery: the clear key resets the entry.
• Continuation: the user selects an operation or evaluates.

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

• Trigger: the user presses an operator key.
• Observable result: the selected operator is reflected in the running expression and the active operator is highlighted in amber.
• Failure/recovery: an operator entered without a preceding operand is not applied; the user can correct the entry.
• Continuation: the user enters the next operand.

FR-5 — Result evaluation (required_inference) As a Calculator User, I should evaluate the expression with the equals key, so that I can see the computed result.

• Trigger: the user presses the equals key.
• Observable result: the computed result appears in the amber result line and the display cross-fades to the result; the particle field shifts hue toward teal for 800ms.
• Failure/recovery: an invalid or incomplete expression or division by zero does not produce a result; the display retains the last valid entry so the user can correct it.
• Continuation: the user can continue calculating from the result or clear and start again.

FR-6 — Clear and reset (required_inference) As a Calculator User, I should clear the current entry and reset the calculation, so that I can start a new calculation.

• Trigger: the user presses the clear key.
• Observable result: the display and expression reset to the initial empty state.
• Continuation: the user begins a new calculation.

FR-7 — Generative field response (explicit, from creative direction) As a Calculator User, I should see the background particle field respond to the digits on screen and to a computed result, so that the calculator feels like a crafted instrument.

• Trigger: digits are entered or a result is computed.
• Observable result: the field is seeded by the digits on screen and shifts hue toward teal for 800ms on result.
• Failure/recovery: with reduced motion, the field freezes into a static render; the calculator remains fully usable.
• Continuation: the user continues calculating.

4. User Personas

Calculator User

Product context. The Calculator User is the anonymous person who opens venus-calculator to do quick arithmetic. They arrive with no account and no prior state; the page is the entire product.

Primary goal. Enter numbers and an arithmetic operation and read the computed result quickly and clearly.

Distinct accepted responsibilities. The Calculator User is the sole active human actor. They initiate every action: entering digits and a decimal point, selecting an operation, evaluating with equals, and clearing to start again. They also observe the page's response — the running expression, the result line, and the generative field reacting to their digits.

Relevant inputs and decisions. The user decides which digits to enter, which operation to apply, and when to evaluate or clear. Their inputs are key presses on the keypad.

Interactions with other accepted participants. There are no other accepted human participants. The only other actor is the system itself, which computes and displays results and renders the particle field.

Observable success. The user sees their entered digits in the display, the selected operator reflected in the expression, and the computed result in the amber result line — with the particle field responding to the arithmetic.

5. Core User Flows

Flow 1 — Perform a basic calculation

1. The Calculator User opens the Calculator page. The page is anonymous and immediately usable; the calculator panel appears with an empty display and the particle field drifting behind it.
2. The user presses digit keys to enter the first operand. The digits appear in the numeric display and the running expression; the particle field is seeded by the digits on screen.
3. The user presses an operator key. The operator appears in the running expression and the active operator is highlighted in amber.
4. The user presses digit keys to enter the second operand. The digits appear in the display.
5. The user presses the equals key. The computed result appears in the amber result line, the display digits cross-fade to the result, and the particle field shifts hue toward teal for 800ms.
6. The user reads the result. They may continue calculating from the result or clear and start again.

Flow 2 — Correct an entry

1. The Calculator User is mid-calculation and has entered an incorrect digit or an incomplete expression.
2. The user presses the clear key. The display and expression reset to the initial empty state.
3. The user re-enters the intended digits and operation.
4. The user presses equals and reads the corrected result.

Flow 3 — Encounter an invalid expression

1. The Calculator User enters an expression that cannot be evaluated (for example, an operator with no following operand, or division by zero).
2. The user presses the equals key. No result is produced; the display retains the last valid entry so the user can see what needs correcting.
3. The user corrects the entry or presses clear to reset.
4. The user completes a valid calculation and reads the result.

Flow 4 — Reduced-motion use

1. The Calculator User has prefers-reduced-motion enabled and opens the Calculator page.
2. The particle field renders as a static image and key-press scaling is removed.
3. The user performs arithmetic exactly as in Flow 1; all controls remain fully usable and results display normally.

6. Visuals Colors and Theme

Muse and headline. After Refik Anadol — Arithmetic as a data sculpture. The calculator is a machine that transforms discrete inputs into flowing numeric output; the page treats the numbers as living material inside a luminous generative field.

Mode. Dark mode.

Colour tokens (exact hex by role)

• Background (near-black ground, ~70% of page): #07080C
• Surface (calculator panel, graphite): #101320
• Text (warm off-white, ≥ 7:1 on ground): #F2F0EA
• Primary (warm amber — active operator, equals key, result digits): #E8B04B
• Accent (cool teal — generative particle field, smallest micro-labels): #4FE3C1
• Muted (secondary labels only): #7C8399

Typography

• Headings and body: Space Grotesk. Space Grotesk Medium for the wordmark and section labels; uppercase micro-labels at 11px with 0.18em tracking.
• Numeric display: Space Grotesk Light at very large sizes, tabular numerals, tight -0.03em tracking.
• Scale: 1.25 modular with a display outlier — 96/64/40/24/16/12; numeric display clamp(64px, 12vw, 140px); micro-labels 11px; keypad values 22–28px.

Shape language

• A single rounded-rect calculator panel with 20px continuous-corner radius, floating over a full-bleed generative particle canvas.
• Keys are soft 14px-radius squares in graphite with hairline 1px borders; the equals key is a full-width amber capsule.
• A curved section boundary where the particle field fades into the panel; thin luminous rules separate the display from the keypad.

Layout

• Single page, two-layer composition: the generative particle canvas fills the viewport as a background layer; centered on top sits a 360px-wide (mobile) to 420px-wide (desktop) calculator panel.
• Above the panel, a small uppercase wordmark "VENUS / CALCULATOR" and a one-line caption sit flush-left within the panel's column.
• On wider screens the panel is offset slightly left of center with the particle field breathing asymmetrically to the right; on mobile the panel occupies the safe width with 24px margins and the canvas remains visible behind it.

Imagery. No photography. The only visual asset is a real-time generative particle field rendered from the calculator's own numeric state — the digits entered and the result seed a flowing, ink-like data wash in teal and amber on black.

Avoid. White or near-white background; blue or indigo primary/accent buttons; centered headline + subtext + gradient-blob SaaS hero; grid of identical hover-lift cards; Inter, Roboto, Arial, Helvetica, system-ui for headings or body; photographic or stock imagery; bouncy or playful easing; crowding the particle field with decorative icons or chrome.

7. Signature Design Concept

The first screen is a full-bleed black generative canvas with a flowing teal-and-amber particle field, and a single floating graphite calculator panel offset left of center. The dominant element is the numeric display — oversized Space Grotesk Light digits in warm off-white with the amber result line beneath — sitting above a quiet 4-column keypad. The wordmark is a small uppercase label in the top-left of the panel column, not a centered SaaS header. There is no hero image and no gradient blob: the generative field is the atmosphere and the calculator is the object.

The signature move is that the particle field is seeded by the digits on screen, so the background visibly responds to arithmetic — the data sculpture is the page. On result, the field shifts hue toward teal for 800ms and the display digits cross-fade, a data-driven transition rather than a generic hover lift. The equals key is a full-width amber capsule that pulses once when pressed, while all other keys stay graphite with hairline borders — one hot accent, one action. A thin luminous rule separates display from keypad, and a second rule under the wordmark, echoing Anadol's museum-label framing.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: webgl

Landing Hero Motion Brief

• Focal subject. The real-time generative particle field, seeded by the calculator's own numeric state — the digits entered and the result — rendered as a flowing, ink-like data wash in teal and amber on black.
• Input → transformation → outcome thesis. Each digit entered seeds the field; each computed result shifts the field's hue toward teal for 800ms while the display digits cross-fade. The atmosphere is a direct function of the arithmetic on screen.
• Motion vocabulary. Continuous slow generative drift (60–90s cycle); subtle brightening and hue shift toward teal on result; 120ms scale-down with a warm amber flash on key press; display number cross-fade on update.
• Composed first frame. Full-bleed black canvas with the particle field drifting; the graphite calculator panel offset left of center; the wordmark "VENUS / CALCULATOR" flush-left above the panel; the oversized numeric display at its initial zero state with the amber result line beneath; the quiet 4-column keypad below a thin luminous rule.
• Reduced-motion state. The particle field freezes into a static render and key-press scaling is removed; the calculator remains fully usable and all results display normally.

Landing Hero 3D Scene Brief — DIRECTION-DERIVED

A single crafted real-time particle system rendered on a full-bleed WebGL canvas: tens of thousands of points flowing in a slow, ink-like drift on a near-black ground, tinted teal and amber. The scene is seeded by the digits currently on the calculator display, so the field's density and hue visibly derive from the arithmetic state; on a computed result the field shifts hue toward teal for 800ms. The calculator panel floats above the canvas as a graphite surface with a 20px continuous-corner radius. The scene must not cover or obscure any readable text or control; the panel and its contents remain fully legible at 375px, 768px, and 1280px.

9. Non-Functional Requirements

NFR-1 — Single page (explicit) The product must be presented on exactly one page. No additional pages, routes, or navigation destinations are part of the current scope.

NFR-2 — Simplicity (explicit) The design must be simple: the calculator is immediately understandable, with no extraneous product surfaces.

NFR-3 — Readable text and controls (explicit, from creative direction) Headlines, wordmarks, labels, numbers, and controls must stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example, font-size: clamp(...)) to fit. No other element may cover any part of them. Imagery, decoration, and motion may be cropped or bled off an edge as the direction asks, as long as they cover no readable text or control.

NFR-4 — Contrast (explicit, from creative direction) Body text and controls use warm off-white #F2F0EA at ≥ 7:1 contrast on the #07080C ground.

NFR-5 — Reduced motion (explicit, from creative direction) With prefers-reduced-motion, the particle field freezes into a static render and key-press scaling is removed, while the calculator remains fully usable.

NFR-6 — No photography (explicit, from creative direction) No photographic or stock imagery is used; the generative particle field is the only visual asset.

10. Tech Stack

• Frontend: React, single-page application.
• 3D / generative rendering: WebGL via React Three Fiber (R3F) for the real-time particle field, as required by the direction's webgl hero dimensionality.
• Styling: CSS with the specified tokens (Space Grotesk via web font, exact hex palette, clamp-based type scale).
• Backend: None required for current scope; all arithmetic and rendering occur client-side on the single page.

11. Assumptions and Constraints

• A-1 (explicit) The design must be simple.
• A-2 (explicit) The design must be a single page.
• A-3 (explicit) The product is "a simple single page design of calculator."
• A-4 (required_inference) The calculator supports the four basic arithmetic operations (add, subtract, multiply, divide), a decimal point, equals, and clear — the indispensable mechanics for a usable calculator lifecycle.
• A-5 (required_inference) The page is anonymous and requires no identity; no account, sign-in, or saved state exists.
• A-6 (explicit, from creative direction) The particle field is decoration and atmosphere seeded by the calculator's numeric state; it does not create additional product capability.
• A-7 (explicit, from creative direction) The generic indigo/blue-on-white SaaS template is forbidden for this project.

12. Glossary

• Calculator User — The single active human actor who opens the page and performs arithmetic.
• Expression — The sequence of entered operands and operators shown in the running expression area.
• Operand — A numeric value entered by the user.
• Operator — An arithmetic operation (add, subtract, multiply, divide) selected by the user.
• Result — The computed numeric outcome of the expression, shown in the amber result line.
• Particle field — The full-bleed generative WebGL background seeded by the digits on screen.
• Panel — The floating graphite calculator surface with a 20px continuous-corner radius.
• Reduced motion — The prefers-reduced-motion state in which the particle field freezes and key-press scaling is removed.