System Requirements Document for verdant-page

1. Introduction

verdant-page is a simple calculator delivered as a single-page design. The product intent is narrow and explicit: one page on which a visitor can enter numbers and arithmetic operators to build a calculation, see the current expression and the computed result, and clear the calculation to start over. The design must be simple and must remain a single page.

The audience is anyone who needs quick, accurate everyday arithmetic from one self-contained page — no account, no navigation, no surrounding application. The page is both the introduction to the calculator and the calculator itself.

This document is the System Requirements Document for the project. It specifies the single page, its components and states, the functional behavior of composing, evaluating, and clearing a calculation, the one active persona, the end-to-end flows, and the visual and technical direction.

2. System Overview

verdant-page is a single-page web calculator. A React frontend renders one page — Calculator — containing a header band with a circular badge stamp and an oversized wordmark, a bordered paper chassis holding an ink-black display panel (live expression line plus oversized tabular readout), a 4-column key grid with a tall orange equals key, and a full-width AC key beneath the grid. A shared FastAPI backend and a MariaDB database are provisioned as infrastructure; the calculator's arithmetic is performed in the page itself, so no application-owned persistent data or domain entities are required by the accepted behavior.

Actors:

• Calculator User (active human persona) — opens the page, enters numbers and operators, reads the expression and result, and clears the calculation.
• Frontend (React application) — renders the page and performs the arithmetic and display state transitions.
• Backend (FastAPI) and Database (MariaDB) — provisioned shared infrastructure; they do not add product behavior, identity, or stored calculation history.

Accepted behavior: composing a calculation from digits, a decimal point, and the four arithmetic operators; displaying the current expression and the computed result; clearing the calculation. Access is public and anonymous — no identity, account, or session continuity is required or provided.

Removed from scope

• User accounts, sign-in, and identity establishment
• Saved or historical calculations and any persistent calculation storage
• Multi-page navigation, menus, or additional destinations
• Scientific functions, memory keys, percentages, and other calculator modes beyond the accepted keys

2a. Product Interpretation and Delivery Boundary

The product is a single, publicly reachable page. There is no anonymous-to-authenticated boundary because no accepted behavior requires identity: a visitor opens the page and immediately has the full calculator. All calculation state lives in the page for the duration of the visit; nothing is persisted, resumed, or shared between visitors.

The delivery boundary is the one page named Calculator. Everything the user does — building an expression, reading the result, clearing — happens within that page. The provisioned backend and database exist as shared infrastructure but carry no calculator domain responsibility in the current scope; they are not user-facing surfaces and do not introduce stored data, accounts, or history. Future ideas (for example, additional calculator functions or saved history) are out of current scope and are not represented on the page.

2c. Page Content and Component Coverage

Calculator

Information and state

• Current expression string (digits, decimal point, operators) shown in a muted-ink expression line at the top-right of the chassis.
• Current computed result shown as oversized cream tabular numerals, right-aligned, on the ink-black display panel.
• Idle/initial state: expression empty, readout showing 0.
• Composing state: expression accumulating as keys are pressed; readout reflects the current value or last computed result.
• Result state: after =, the readout shows the computed result and the expression line shows the evaluated expression.
• Error state: an invalid or undefined operation (for example division by zero) shows a clear error indication in the readout instead of a number.
• Cleared state: after AC, expression empty and readout back to 0.

Primary actions

• Press digit keys 0–9 to append digits to the current number.
• Press . to enter a decimal point in the current number.
• Press operator keys +, −, ×, ÷ to set the pending operation.
• Press the tall orange = key to evaluate the expression and show the result.
• Press the full-width AC key to clear the calculation and start over.

Supporting actions and controls

• Every key is a real button with a 3px ink border and 4px hard offset shadow that collapses on press; keys are keyboard-focusable with a visible focus ring in field-notes orange.
• Keys respond to pointer press and to keyboard activation.

Domain entities

• Calculation (in-page only): the expression being built and its evaluated result. Not persisted.

Component responsibilities

• Header band: circular badge stamp with concentric rings at left; oversized all-caps Alfa Slab One wordmark spanning the column; construction-tape stripe band (ink and orange diagonals) as the single section edge beneath the header.
• Chassis panel: bordered paper surface containing the expression line, display panel, key grid, and AC key.
• Expression line: displays the live expression in muted ink, right-aligned.
• Display panel: ink-black inset panel showing the readout in cream Oswald tabular numerals, right-aligned.
• Key grid: 4 columns — 7 8 9 ÷ / 4 5 6 × / 1 2 3 − / 0 . = + — with = as the tall orange key spanning two rows at the right edge.
• AC key: full-width key beneath the grid.
• Footer: single ruled line with small-caps plain-talk copy.

States

• Loading: not applicable — the page renders its static calculator immediately; no data fetch is required.
• Empty: initial and cleared state show 0 with an empty expression line.
• Success: valid evaluation shows the numeric result in the readout and the evaluated expression above it.
• Error: invalid/undefined operation shows an error message in the readout; the user recovers by pressing AC or entering a new number.
• Recovery: AC always returns the page to the cleared state; entering a digit after an error begins a fresh calculation.

3. Functional Requirements

FR-1 — Single-page calculator delivery (explicit) As a Calculator User I should reach the entire calculator on one page so that I can do arithmetic without navigating anywhere.

• Trigger: opening the page.
• Observable result: the Calculator page renders the header, chassis, display, key grid, and AC key; there are no other destinations.
• Access: public, anonymous.
• Failure/recovery: not applicable; the page is self-contained.
• Continuation: the user may immediately begin entering a calculation.

FR-2 — Enter numbers and operators to build a calculation (explicit) As a Calculator User I should enter numbers and arithmetic operators so that I can build the calculation I want.

• Trigger: pressing digit keys 0–9, ., and operator keys +, −, ×, ÷.
• Observable result: the expression line updates to show the digits and operators entered; the readout reflects the current number.
• Access: public, anonymous.
• Failure/recovery: pressing an operator with no current number is ignored or leaves the expression unchanged; the user continues entering digits.
• Continuation: the user keeps adding numbers and operators or presses =.

FR-3 — See the current expression and computed result (explicit) As a Calculator User I should see the current expression and its computed result so that I can confirm what I am calculating and read the answer.

• Trigger: entering keys and pressing =.
• Observable result: the expression line shows the current expression in muted ink; the display panel shows the computed result in oversized tabular numerals.
• Access: public, anonymous.
• Failure/recovery: an invalid or undefined operation (for example division by zero) shows an error indication in the readout; the user recovers via AC or a new number.
• Continuation: the user may continue from the result or start a new calculation.

FR-4 — Clear the calculation to start over (explicit) As a Calculator User I should clear the calculation so that I can start over cleanly.

• Trigger: pressing the full-width AC key.
• Observable result: the expression line empties and the readout returns to 0.
• Access: public, anonymous.
• Failure/recovery: AC is always available and always returns the page to the cleared state, including from an error state.
• Continuation: the user begins a new calculation.

4. User Personas

Calculator User

Product context. The Calculator User opens verdant-page to perform quick, accurate everyday arithmetic. They arrive with no account and no prior state; the page is a self-contained utility they use in the moment and leave.

Primary goal. Get an accurate result from a calculation they build on the page, with minimal friction.

Distinct accepted responsibilities.

• Enter numbers and arithmetic operators to compose a calculation.
• Read the current expression and the computed result.
• Clear the calculation to start over.

Relevant inputs and decisions. The user decides which digits, decimal point, and operators to enter, when to press = to evaluate, and when to press AC to reset. They read the expression line to confirm what they have entered and the display panel to read the answer.

Interactions with other participants. The Calculator User is the only active human participant. The frontend performs the arithmetic and display updates in response to their key presses; no other human participant is involved, and no handoff or shared state exists.

Observable success. The display shows the correct computed result for the expression entered, and AC reliably returns the page to a clean 0 state for the next calculation.

5. Core User Flows

Flow A — Compose and evaluate a calculation

1. The Calculator User opens the Calculator page. The page renders with an empty expression line and a readout of 0.
2. The user presses digit keys to enter the first number; the digits appear in the expression line and the readout.
3. The user presses an operator key (+, −, ×, or ÷); the operator appears in the expression line.
4. The user presses digit keys to enter the second number; the expression line shows the full expression.
5. The user presses the tall orange = key. The frontend evaluates the expression and the display panel shows the computed result in oversized tabular numerals, with the evaluated expression above it.
6. The user reads the result. They may continue building on it or start a new calculation.

Failure/recovery. If the expression is invalid or undefined (for example division by zero), the readout shows an error indication. The user presses AC to clear, or enters a new number to begin again.

Flow B — Clear the calculation

1. The Calculator User, at any point during or after a calculation, presses the full-width AC key.
2. The expression line empties and the readout returns to 0.
3. The user begins a new calculation from a clean state.

Failure/recovery. AC is always available, including from an error state, and always returns the page to the cleared state.

Flow C — Correct an entry mid-calculation

1. The Calculator User notices an incorrect entry in the expression line.
2. The user presses AC to clear and re-enters the calculation from the start.
3. The expression line and readout reflect the corrected calculation, and the user presses = to evaluate.

6. Visuals Colors and Theme

The creative direction is authoritative: Honest arithmetic, hand-built after Aaron Draplin. The register is sturdy, plain-spoken, and satisfying to press — workwear colours, thick strokes, badge geometry, and all-caps labels.

Colour tokens (light mode)

• Background (kraft ground): #E8DCC3
• Surface (paper chassis): #F3EAD6
• Text / ink: #1C1A17
• Primary (ink): #1C1A17
• Accent (field-notes orange): #E4571E — equals key, operator keys, focus rings, the one badge stamp
• Muted (kraft-brown): #8A7C63 — secondary labels and hairline rules
• Mustard #D9A227 and denim #2F4A63 — tiny badge/rule details only, never large fields
• No blue as a primary or accent; no white-first surface.

Typography

• Headings and display numerals: Alfa Slab One — heavy slab, tight leading, all-caps for the wordmark.
• Body and key labels: Oswald — medium/semibold, uppercase with wide tracking for key labels and micro-labels; tabular figures on the display.
• Scale (1.25 modular): wordmark clamp(40px, 9vw, 104px); display readout clamp(44px, 8vw, 88px) tabular; expression line 18–22px; key labels 20–26px uppercase; micro-labels 11–12px with 0.14em tracking.

Shape language

• Thick 3px ink borders and 4px hard offset shadows on every key and panel — no blur, no soft drop shadows.
• Rounded-rectangle keys with 10px radii, chunky and pressable.
• Badge/stamp geometry: circular stamp with concentric rings for the header mark; ruled horizontal dividers; construction-tape stripes (ink and orange diagonal bands) as a single section edge.
• Hard edges everywhere else; nothing pill-shaped, nothing glassy.

Layout

• One centred column, max-width 480px for the calculator chassis, on a full-bleed kraft ground.
• Full-width header band with the badge stamp at left and the wordmark spanning the column.
• Chassis is a bordered paper panel: expression line top-right in muted ink, big readout beneath it on an ink-black display panel with cream numerals, then a 4-column key grid — 7 8 9 ÷ / 4 5 6 × / 1 2 3 − / 0 . = + — with equals as the tall orange key spanning two rows at the right, and a full-width AC key beneath the grid.
• Below the chassis, a single ruled footer line with small-caps plain-talk copy.
• At 375px the chassis fills the viewport minus 16px gutters and keys stay at least 48px tall; at 768px it centres with 48px margins; at 1280px the header band lets the wordmark run wide while the chassis stays 480px.

Imagery

• No photography and no 3D. Draplin's thick-line vector language: the circular badge stamp, a small set of 2px-stroke pictogram glyphs for + − × ÷ = set inside the keys, ruled panels, and flat shapes. A single halftone-dot texture may sit at low opacity on the kraft ground as paper grain.

7. Signature Design Concept

The first screen is the calculator itself as a piece of equipment, not a marketing hero. A full-bleed kraft ground carries a header band across the top with a circular badge stamp at the left and the Alfa Slab One wordmark set oversized in ink. Beneath it, the bordered paper chassis dominates the centre with its ink-black display panel holding an oversized tabular readout. The orange equals key is the only hot accent in the frame and reads instantly as the destination of the eye. There is no centred headline-plus-subtext-plus-button stack, no gradient, and no floating card grid — the dominant element is the physical key grid with its hard offset shadows.

Signature moves:

• Every key and the chassis carry a 3px ink border with a 4px hard offset shadow that collapses to zero on press, so the calculator reads as a stamped physical instrument.
• A tall orange equals key spans two rows at the right edge of the 4-column grid — the single hot accent and the visual terminus of every calculation.
• The display is an ink-black panel inset in the paper chassis with cream Oswald tabular numerals at clamp(44px, 8vw, 88px), right-aligned, with the live expression in muted ink above it.
• A circular badge stamp with concentric rings sits at the left of the header band, paired with an oversized all-caps Alfa Slab One wordmark that runs the full column width.
• A construction-tape stripe band (ink and orange diagonals) forms the single section edge beneath the header, drifting slowly as the only ambient motion.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the calculator chassis and its physical key grid, with the tall orange equals key as the visual terminus.
• Input → transformation → outcome thesis: a key press depresses the key by translate(2px, 2px) over 90ms, collapsing its hard offset shadow to zero — a real button press with no bounce — and the display digits snap in without easing to show the updated expression or result.
• Motion vocabulary: restrained and mechanical. Keys depress with a 90ms translate that collapses the hard offset shadow; display digits snap in without easing; one purposeful loop only — a slow diagonal drift of the construction-tape stripe band at the header edge.
• Composed first frame: full-bleed kraft ground, header band with badge stamp and oversized wordmark, bordered paper chassis centred with ink-black display panel showing 0, and the 4-column key grid with the orange equals key spanning two rows.
• Reduced-motion state: with prefers-reduced-motion, the stripe holds still and key presses become a colour flash instead of movement; the display continues to update.

9. Non-Functional Requirements

• Single page (explicit): the product is delivered as exactly one page; no additional routes, menus, or destinations.
• Simplicity (explicit): the design and interaction remain simple — a plain key grid, a display, and a clear key.
• Readable text and controls (explicit, from design constraints): headlines, wordmarks, labels, numbers, and controls 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.
• Accessibility (required_inference): keys are keyboard-focusable with a visible focus ring in field-notes orange; key targets are at least 48px tall at 375px; reduced-motion preferences are honored.
• No persistence (required_inference): calculation state is in-page only; no calculation data is stored in the database or backend.
• Performance (required_inference): the page renders immediately with no data fetch; key presses update the display without perceptible delay.

10. Tech Stack

• Frontend: React application rendering the single Calculator page.
• Backend: shared FastAPI process for application APIs and domain modules (provisioned; no calculator domain responsibility in current scope).
• Database: MariaDB for application-owned persistent data (provisioned; no calculator data stored in current scope).
• Deployment: docker-compose with the backend, database, and frontend services.

11. Assumptions and Constraints

• The calculator performs standard arithmetic on the four operators +, −, ×, ÷ with a decimal point; no scientific functions, memory, or percentages are in scope.
• The page is public and anonymous; no identity, account, or session continuity is required.
• Calculation state is not persisted; the database and backend carry no calculator data.
• The creative direction (Draplin-inspired kraft/ink/orange, Alfa Slab One and Oswald, hard offset shadows, construction-tape stripe) is authoritative for visuals and motion.
• The generic indigo/blue-on-white SaaS template is forbidden for this project.

12. Glossary

• Calculator page: the single page of verdant-page hosting the calculator.
• Chassis: the bordered paper panel containing the display and key grid.
• Expression line: the muted-ink line showing the current expression.
• Display panel: the ink-black inset panel showing the computed result in cream tabular numerals.
• AC key: the full-width clear key that resets the calculation.
• Equals key: the tall orange key spanning two rows that evaluates the expression.
• Construction-tape stripe: the ink and orange diagonal band forming the section edge beneath the header.