System Requirements Document for pearl-start

1. Introduction

pearl-start is a simple calculator delivered as a single-page design. The product intent is narrow and deliberate: one page where a person can enter numbers and arithmetic operators to build an expression, evaluate it to see the computed result, and clear the current entry or calculation to start over. There is no account, no dashboard, no navigation, and no brand storytelling — the calculator is the page.

The audience is anyone doing quick everyday arithmetic who wants a calm, obvious tool they can pick up, use, and put down without ceremony. The design language follows a "super normal" everyday-object register: a soft-white calculator panel on a warm paper-grey ground, physical key caps, a recessed display well, and a single terracotta accent reserved for the operator column and the equals key.

The single hard constraint from the requester is that the design is a single page. Everything in this document is scoped to that one page.

2. System Overview

2a. Product Interpretation and Delivery Boundary

pearl-start is a first-party, single-page web calculator. The one accepted page, Calculator, is the public entry surface and is anonymously reachable: no identity, sign-in, session, or account is required or established, because the accepted behavior is stateless arithmetic that produces no durable actor-specific state, commitment, entitlement, or value transfer. There is no protected destination and therefore no first-use identity establishment or returning verification.

All accepted human work — building an expression, evaluating it, reading the result, and clearing — happens on the Calculator page in the browser. The provisioned shared FastAPI backend and MariaDB database exist as infrastructure but carry no accepted domain responsibility for this product: the calculator's arithmetic is a client-side interaction, and no accepted requirement asks for persistence, history, or server-side computation. They are not used to justify accounts, saved calculations, or any adjacent capability.

Current delivery is the single Calculator page only. Nothing beyond it is in scope now.

2b. Source Content Inventory

Not applicable — no reference directive supplies a content_source.

2c. Page Content and Component Coverage

Calculator

The single page of the product. It is anonymously reachable and hosts the entire calculator lifecycle: expression entry, evaluation, result display, and clearing.

Information and state

• Current expression being built (the sequence of entered numbers and operators).
• Current display value: either the in-progress entry or the computed result after evaluation.
• An evaluated-result state, distinct from an in-progress entry state, so the user can tell a landed result from a number still being typed.
• An empty/initial state on first load: display shows a zero baseline and no pending expression.
• An error state when an expression cannot be evaluated (for example, division by zero or a malformed expression).

Primary actions

• Enter digits to build a number.
• Enter arithmetic operators to build an expression.
• Evaluate the expression (equals) to compute and show the result.
• Clear the current entry or the whole calculation to start over.

Supporting actions

• Continue a calculation from a landed result by entering a new operator or number.

Domain entities

• Expression: the ordered sequence of numbers and operators the user has entered.
• Entry: the number currently being typed.
• Result: the computed value produced by evaluation.
• Operator: an arithmetic operation joining two operands.

Component responsibilities

• Wordmark: small "pearl" wordmark above the calculator panel, Jost caps with wide tracking.
• Display well: recessed panel at the top of the calculator showing large tabular digits; carries the current entry or result; shows the error state in place of digits when evaluation fails.
• Keypad: 4-column grid of physical key caps — digit keys, operator keys (terracotta), equals key (terracotta), and clear key — each with a 1px bottom lip shadow and a 2px press depression.
• Plain-language note: a single muted 11px caps line beneath the calculator — "a calculator. nothing else." — the page's only editorial voice.
• Page ground: warm paper-grey background with an optional faint paper-grain texture at 3% opacity; no header nav, no footer links, no cards.

States

• Loading: none required — the page is static markup and client-side arithmetic; it renders immediately.
• Empty: initial load shows the zero baseline display and an empty expression.
• Success: evaluation lands a result in the display well with a 120ms cross-fade of the digits.
• Error: an unevaluable expression shows an error indication in the display well; the user recovers by clearing and re-entering.
• Recovery: the clear control resets the entry or the whole calculation back to the empty state at any time.

3. Functional Requirements

FR-1 — Single-page calculator delivery (explicit) As a Calculator User, I should get the calculator as a single page, so that the whole tool is in one place with nothing to navigate.

• Trigger: the user opens the product.
• Observable result: exactly one page, the Calculator page, renders with the calculator panel as its only object of attention.
• Access: anonymous; no identity or session.
• Failure/recovery: not applicable — the page is static and renders immediately.
• Continuation: the user proceeds directly to entering an expression.

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

• Trigger: the user presses digit keys and operator keys on the keypad.
• Input: digit key presses append to the current entry; operator key presses join the current entry to the expression.
• Observable result: the display well shows the digits being entered, and the expression accumulates the entered numbers and operators.
• Access: anonymous.
• Failure/recovery: if the user mis-enters, the clear control (FR-4) resets the entry or calculation.
• Continuation: the user either keeps building the expression or evaluates it (FR-3).

FR-3 — Evaluate the expression and see the computed result (explicit) As a Calculator User, I should evaluate the expression and see the computed result, so that I get the answer to my arithmetic.

• Trigger: the user presses the equals key.
• Input: the current expression.
• Observable result: the display well shows the computed result, with the digits cross-fading in over 120ms.
• Access: anonymous.
• Failure/recovery: if the expression cannot be evaluated (for example, division by zero or a malformed expression), the display well shows an error indication instead of a result; the user clears and re-enters.
• Continuation: the user can continue calculating from the landed result by entering a new operator or number.

FR-4 — Clear the current entry or calculation to start over (explicit) As a Calculator User, I should clear the current entry or calculation to start over, so that I can correct a mistake or begin a new calculation.

• Trigger: the user presses the clear key.
• Observable result: the current entry or the whole calculation is reset, returning the display to the empty state.
• Access: anonymous.
• Failure/recovery: not applicable — clearing always succeeds and is the recovery path for FR-2 and FR-3.
• Continuation: the user begins a new expression.

4. User Personas

Calculator User

Product context. The Calculator User is anyone doing quick everyday arithmetic — a sum, a difference, a product, a quotient — who wants the answer without ceremony. They arrive at the single Calculator page anonymously, with no account and no history to resume, and they expect to understand the tool in one second.

Primary goal. Get the correct arithmetic result without leaving the page.

Distinct accepted responsibilities.

• Enter numbers and arithmetic operators to build an expression (FR-2).
• Evaluate the expression and read the computed result (FR-3).
• Clear the current entry or calculation to start over when they mis-enter or want a fresh calculation (FR-4).

Relevant inputs and decisions. Digit key presses, operator key presses, the equals key, and the clear key. The user decides when an expression is complete enough to evaluate and whether to continue from a result or clear and start again.

Interactions with other accepted participants. None — the Calculator User is the only accepted human persona, and the calculator's arithmetic is a direct interaction between the user and the page. There is no counterparty, recipient, or beneficiary whose state changes.

Observable success. The display well shows the correct computed result after evaluation, and the user can clear and start a new calculation at any time without leaving the page.

5. Core User Flows

Flow 1 — Perform a calculation

1. Start. The Calculator User opens the product and lands on the Calculator page. The page renders immediately with the calculator panel centred on the warm ground, the "pearl" wordmark above it, and the plain-language note beneath. The display well shows the zero baseline and the expression is empty.
2. Enter the first number. The user presses digit keys. Each key depresses 2px and releases; the digits appear in the display well as large tabular numerals.
3. Enter an operator. The user presses an operator key in the terracotta operator column. The operator joins the first number to the expression.
4. Enter the second number. The user presses digit keys for the second operand; the display well shows the digits being entered.
5. Evaluate. The user presses the terracotta equals key. The expression is computed and the result lands in the display well, the digits cross-fading in over 120ms.
6. Read the result. The user reads the computed result in the display well. Success is the correct answer, visible without leaving the page.
7. Continue or finish. The user either continues calculating from the landed result by entering a new operator or number, or puts the tool down. There is no save, no history, and no next destination.

Flow 2 — Correct a mistake or start over

1. Start. The Calculator User is on the Calculator page with an entry or expression in progress, or a landed result in the display well.
2. Recognize the need to reset. The user sees a mis-entered number or wants a fresh calculation.
3. Clear. The user presses the clear key. The current entry or the whole calculation is reset and the display returns to the empty state.
4. Re-enter. The user begins a new expression by pressing digit and operator keys, following Flow 1 from step 2.

Flow 3 — Recover from an unevaluable expression

1. Start. The Calculator User has built an expression that cannot be evaluated (for example, division by zero or a malformed expression) and presses the equals key.
2. See the error. The display well shows an error indication in place of a result.
3. Recover. The user presses the clear key; the display returns to the empty state.
4. Continue. The user re-enters a valid expression and evaluates it, following Flow 1 from step 2.

6. Visuals Colors and Theme

The creative direction — Super normal arithmetic, after Naoto Fukasawa — is authoritative for this section.

Mode. Light mode only.

Colour tokens (exact hex by role)

• Background / page ground: #F2F0EB (warm paper-grey)
• Surface / calculator body: #FBFAF7 (soft white)
• Hairline edge and dividers: #E2DED6
• Text / display digits and labels: #23211E (ink)
• Primary key fill: #2E2B27 (dark keys, white glyphs)
• Accent: #C4663F (terracotta) — reserved for the operator column and the equals key only, roughly 5% of pixels
• Muted: #8C877E — micro-labels and secondary metadata

No second accent, no gradients, no blue or indigo, no white-first ground with a coloured button.

Typography

• Headings and wordmark: Jost at 500–600 with slightly open tracking (+0.01em).
• Digit display: Jost 400 at very large size with tabular numerals and tight leading (line-height 1.0), so digits read as machined, evenly spaced forms.
• Body: Karla, 16/17px, line-height 1.45.
• Micro-labels: 11px all-caps with +0.14em tracking.
• Scale: 1.25 modular — display digits clamp(48px, 9vw, 96px) tabular; wordmark clamp(22px, 3vw, 30px); key glyphs clamp(20px, 3.4vw, 28px).
• Inter, Roboto, Arial, Helvetica, Poppins, and system-ui are forbidden for any text.

Shape language

• Soft rounded blocks with continuous-curve radii: calculator body 28px radius; keys 16px radius with a 1px bottom lip shadow so each key reads as a physical cap.
• No pills, no blobs, no glossy highlights.
• Hairline 1px #E2DED6 dividers separate the display from the keypad and the keypad from the footer note.
• Everything sits on a calm, slightly off-square grid with 8-pt spacing.

Layout

• One page, one column of attention.
• At 1280px the calculator sits as a single centred object roughly 420px wide, tilted 0° (no rotation), with the wordmark above it and the one-line note beneath.
• At 768px the object widens to ~90% of a 560px column.
• At 375px it becomes a full-width card with 16px gutters, keys in a 4-column grid that keeps every glyph whole.
• Generous whitespace above and below — the page is mostly ground, and the object is the only thing on it.

Imagery

• No photography and no illustration. The calculator itself is the image: a soft-white panel with real key caps, a recessed display well with a hairline inset, and a subtle 1px inner shadow at the top of the display.
• A single faint paper-grain texture at 3% opacity may sit on the background.

Readable text and controls stay whole at 375px, 768px, and 1280px — headlines, wordmarks, labels, numbers, and controls stay entirely inside the viewport and their container, wrapping or scaling with clamp(...) to fit, with no other element covering any part of them.

7. Signature Design Concept

The first screen is the object, not a marketing hero. A soft-white calculator panel sits centred on a warm paper-grey ground, occupying roughly one third of the viewport width at 1280px and nearly full width at 375px. Above the panel, a small "pearl" wordmark in Jost caps with wide tracking; below it, one muted line of plain-language copy — "a calculator. nothing else." — set in 11px caps as the page's only editorial voice.

The dominant element is the calculator's recessed display well: a 1px inset hairline and an inner top shadow make the digits look printed into the panel rather than floating on it, lit as if by a single soft overhead source. The surrounding ground is left almost empty so the object reads as inevitable rather than designed.

The physical key caps carry the concept: each key has a 1px bottom lip shadow and depresses 2px on press, and the equals key is the only terracotta-filled cap on the page, anchoring the bottom-right of the keypad. The terracotta appears on exactly the operator column and the equals key — nowhere else — so the eye learns the arithmetic hierarchy instantly. There is no header nav, no footer links, no cards, no gradient blobs, no glassmorphism, and no drop shadow larger than 2px.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject. The calculator panel itself — specifically its recessed display well with large tabular digits and the terracotta equals key anchoring the bottom-right of the keypad.
• Input → transformation → outcome thesis. A key press (input) depresses the cap 2px with a 90ms ease-out and releases in 140ms (transformation), and the display well reflects the entered digit or, on equals, cross-fades the computed result in over 120ms (outcome). The equals key's terracotta fill brightens slightly on hover. Nothing else moves.
• Motion vocabulary. Still-to-restrained: key depression and release, display digit cross-fade, equals-key hover brightening. No entrance animation, no parallax, no decorative loops, no bouncy or springy key animations.
• Composed first frame. The calculator panel centred on the warm ground at rest, display well showing the zero baseline, wordmark above, plain-language note beneath, the rest of the page deliberate emptiness.
• Reduced-motion state. Under prefers-reduced-motion, all transitions collapse to instant state changes and the layout is unchanged.

9. Non-Functional Requirements

• Single-page constraint (explicit): the product is exactly one page. No additional routes, pages, or destinations may be introduced.
• Anonymous access (required_inference): the Calculator page is reachable without identity, sign-in, or session, because the accepted behavior is stateless arithmetic with no durable actor-specific state. No account-management capability is in scope.
• Immediate render (basic_default): the page is static markup with client-side arithmetic and renders without a loading state.
• Readable text and controls at every viewport (explicit design constraint): headlines, wordmarks, labels, numbers, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling with clamp(...) to fit, with no other element covering any part of them.
• Reduced motion (explicit design constraint): under prefers-reduced-motion, all transitions collapse to instant state changes and the layout is unchanged.
• No forbidden visual patterns (explicit design constraint): no gradient blobs, glassmorphism, translucent panels, blue or indigo accents, white-first ground with a coloured button, feature cards, testimonials, glossy 3D renders, drop shadows larger than 2px, bouncy key animations, forbidden font families, rotated or perspective-transformed calculator panel, or multiple competing accent colours.

10. Tech Stack

• Frontend: React application UI — the single Calculator page, client-side arithmetic, and the keypad interaction.
• Backend: shared FastAPI process for application APIs and domain modules. Provisioned as infrastructure; no accepted calculator requirement depends on it.
• Database: MariaDB for application-owned persistent data. Provisioned as infrastructure; the calculator's accepted behavior is stateless and requires no persistence.
• Containerization: Docker / docker-compose for the backend, database, and frontend services.

11. Assumptions and Constraints

• Assumption (basic_default): the calculator supports the four basic arithmetic operations (addition, subtraction, multiplication, division) and decimal numbers, as the ordinary meaning of "a simple calculator."
• Assumption (basic_default): arithmetic is evaluated client-side in the browser; no server round-trip is required for evaluation.
• Assumption (basic_default): the provisioned backend and database remain available as infrastructure but carry no accepted domain responsibility for this product.
• Constraint (explicit): the design is a single page — exactly one page, the Calculator page.
• Constraint (explicit): the product is a simple calculator; no adjacent capabilities (history, memory, scientific functions, accounts, dashboards) are in scope.
• Constraint (explicit design constraint): the creative direction's palette, fonts, surfaces, tone, and layout are preserved as specified in Sections 6–8.

12. Glossary

• Calculator page: the single page of the product; the public entry surface hosting expression entry, evaluation, result display, and clearing.
• Expression: the ordered sequence of numbers and operators the user has entered.
• Entry: the number currently being typed, before it is joined to the expression by an operator.
• Result: the computed value produced by evaluating an expression.
• Operator: an arithmetic operation joining two operands; rendered in the terracotta operator column.
• Display well: the recessed panel at the top of the calculator showing large tabular digits, with a 1px inset hairline and inner top shadow.
• Key cap: a physical-looking key with a 1px bottom lip shadow that depresses 2px on press.
• Equals key: the terracotta-filled key that evaluates the expression; the only terracotta-filled cap on the page.
• Clear key: the key that resets the current entry or the whole calculation to the empty state.
• Calculator User: the single accepted human persona; anyone doing quick everyday arithmetic on the Calculator page.