System Requirements Document for todo-list

1. Introduction

todo-list is a deliberately small, single-owner personal task list. Its product intent is captured in one sentence from the requester: create simple todo list. The application lets one person write down tasks, see them in a list, tick them off when done, and scrap the ones they no longer need — nothing more.

The audience is a single everyday user keeping a lightweight personal list of outstanding items and seeing at a glance what is finished. The product is intentionally not a dashboard, not a team tool, and not a project-management system. Simplicity is an explicit hard constraint: every requirement below exists to serve the four core actions (add, view, complete, delete) plus the persistence that makes them meaningful across visits.

Success Criteria

• A first-time visitor can understand what the product is and reach the working list in one step.
• A user can add a todo item, see it appear in the list, mark it complete, and delete it, each in a single obvious interaction.
• Todo items survive a page reload and a return visit on the same device.
• The interface remains fully legible and operable at 375px, 768px, and 1280px viewport widths.

2. System Overview

todo-list is delivered as a small custom web application with three provisioned services:

• frontend — a React application rendering the Landing and Todo List pages.
• backend — a shared FastAPI process exposing the todo-item API used by the frontend.
• database — MariaDB holding the application-owned persistent todo items.

The only active human actor is the Todo List Owner. There are no other human personas, no teams, no sharing, and no differentiated permissions. Both pages are reachable without any sign-in: the Landing page is an anonymous public entry surface, and the Todo List page is the single cohesive workspace where the owner adds, views, completes, and deletes items.

Accepted current behavior: add todo items, view todo items in a list, mark items complete, delete items, and persist items across visits on the same device.

Removed from scope

• None. The authoritative thread contains no explicit removals; the only explicit constraint is that the todo list stay simple.

2a. Product Interpretation and Delivery Boundary

The product is a first-party custom UI backed by a first-party API and database. There is no provider-owned surface, no external destination, and no headless delivery. Access is anonymous on both pages — the Planning Scope contract sets access_requirement: none for Landing and Todo List, and the source never asks for accounts, sign-in, or per-user separation. Persistence is therefore scoped to the device/browser context in which the list is used, matching the accepted requirement that items persist across visits on the same device.

Current horizon: the two pages and the five accepted behaviors above. No future-horizon requirements were stated by the user; nothing beyond the simple list is planned in this document.

2c. Page Content and Component Coverage

Landing

• Purpose and information: anonymous public entry surface that explains the simple todo list and routes the visitor into the list.
• Information/state: oversized TODO wordmark, the tagline line ONE LIST. NO CEREMONY., a short plain-language description of what the list does (add, tick off, scrap), and a tilted sample paper panel showing three ruled rows with one ticked.
• Primary action: a single entry control (all-caps label, e.g. OPEN THE LIST) that navigates to the Todo List page.
• Supporting actions: none required; no sign-in, no settings, no secondary destinations.
• Domain entities: none owned here; the sample rows are static illustration only and are not persisted.
• Component responsibilities: hero block (wordmark, orange rule, tagline), tilted sample panel with circular open-count seal, entry control.
• States: loading — not applicable (static content); empty — not applicable; success — entry control navigates to Todo List; error — not applicable; recovery — if navigation fails the entry control remains available to retry.

Todo List

• Purpose and information: the single cohesive workspace where the owner adds, views, completes, and deletes todo items.
• Information/state: the ordered list of todo items, each with its task text and a complete/incomplete state; an open count and a done count shown in the index rail; an empty state when no items exist.
• Primary actions: add a todo item via a text input plus an add control; toggle an item complete/incomplete via its checkbox; delete an item via its SCRAP stamp.
• Supporting actions: none beyond the three above; no editing, reordering, filtering, or bulk operations are in scope.
• Domain entities: Todo Item — task text, completion state, creation order, and a stable identifier used by the API.
• Component responsibilities: add row (text field, add button), list panel of ruled rows (checkbox, task text, SCRAP stamp), index rail with stamped OPEN / DONE numerals, empty-state block with crossed-pencil pictogram.
• States:
  • Loading: list panel shows a quiet placeholder while items are fetched.
  • Empty: crossed-pencil pictogram, muted-kraft-grey message, add row still active.
  • Success: new row snaps in; checkbox tick draws on; counts update; deleted row is removed.
  • Error: if a fetch fails, an inline message with a retry control appears in the list panel; if an add/toggle/delete request fails, the affected row reverts to its prior state and an inline message explains the failure so the owner can retry.
  • Recovery: retry re-issues the failed request; the list re-renders from the server's authoritative state.

3. Functional Requirements

FR-1 — Add a todo item (explicit) As a Todo List Owner, I should be able to add a todo item to my list, so that I can record something I need to do.

• Trigger/input: the owner types task text into the add field on the Todo List page and activates the add control.
• Observable result: the new item appears at the end of the list with its text and an unchecked checkbox; the open count increments.
• Access state: anonymous; no sign-in required.
• Failure/recovery: empty or whitespace-only input is not accepted and no item is created; if the save request fails, the item is not shown as saved and an inline message lets the owner retry.
• Continuation: the add field clears and stays focused so the owner can add the next item.

FR-2 — View todo items in a list (explicit) As a Todo List Owner, I should be able to view my todo items in a list, so that I can see everything outstanding and what is done.

• Trigger/input: opening the Todo List page, or returning to it after any change.
• Observable result: all saved items render as ruled rows in creation order, each showing its task text and completion state; the index rail shows the open and done counts.
• Access state: anonymous.
• Failure/recovery: if loading fails, an inline error with a retry control is shown instead of a blank panel.
• Continuation: the owner can act on any row directly.

FR-3 — Mark a todo item complete (explicit) As a Todo List Owner, I should be able to mark a todo item as complete, so that I can see at a glance what is done.

• Trigger/input: the owner activates the checkbox on a row.
• Observable result: the checkbox shows a drawn tick, the task text takes the completed strike treatment, the open count decrements and the done count increments; activating the checkbox again returns the item to incomplete.
• Access state: anonymous.
• Failure/recovery: if the update fails, the checkbox reverts to its prior state and an inline message allows retry.
• Continuation: the owner can continue ticking off other rows.

FR-4 — Delete a todo item (explicit) As a Todo List Owner, I should be able to delete a todo item, so that I can remove things I no longer need.

• Trigger/input: the owner activates the SCRAP stamp on a row.
• Observable result: the row is removed from the list and the relevant count updates.
• Access state: anonymous.
• Failure/recovery: if the delete request fails, the row remains in the list and an inline message allows retry.
• Continuation: the owner can keep working on the remaining rows.

FR-5 — Persist todo items across visits on the same device (required_inference) As a Todo List Owner, I should find my todo items still present when I return to the list on the same device, so that my list is useful beyond a single page view.

• Trigger/input: reloading or revisiting the Todo List page on the same device.
• Observable result: the same items, with the same completion states, are shown as before.
• Access state: anonymous; persistence is bound to the device/browser context, not to an account.
• Failure/recovery: if the stored list cannot be loaded, the inline error and retry control from FR-2 apply.
• Continuation: the owner resumes adding, completing, and deleting as normal.

FR-6 — Reach the list from the Landing page (required_inference) As a Todo List Owner, I should be able to go from the Landing page to my list in one step, so that I can start working immediately.

• Trigger/input: activating the entry control on the Landing page.
• Observable result: the Todo List page opens showing the current list.
• Access state: anonymous.
• Failure/recovery: if navigation fails, the entry control remains available to retry.
• Continuation: the owner proceeds with FR-1 through FR-4.

4. User Personas

Todo List Owner

• Product context: a single person keeping a lightweight personal list of things to do. They are not managing a team, a project plan, or shared work; the list is theirs alone and lives on the device they use it from.
• Primary goal: keep a short, honest list of outstanding items and see at a glance what is done.
• Distinct accepted responsibilities: writing down new items, reading the list, ticking items off (and un-ticking them if needed), and scrapping items that no longer matter.
• Relevant inputs or decisions: the task text they type; the decision that an item is finished; the decision that an item should be removed.
• Interactions with other accepted participants: none — this is a single-owner product with no other human participants, no sharing, and no handoffs.
• Observable success: the item they typed appears in the list; the tick they made is visible and reflected in the counts; the item they scrapped is gone; and all of this is still there when they come back.
• What makes this role distinct: the entire product is built around one person's private, low-ceremony task keeping. There is no administrative role, no reviewer, and no collaborator, so the owner's experience is the product.

5. Core User Flows

Flow A — First visit and reaching the list

1. The Todo List Owner opens the site and lands on the Landing page (anonymous).
2. They read the TODO wordmark, the ONE LIST. NO CEREMONY. line, and the short description of what the list does.
3. They activate the entry control.
4. The Todo List page opens. If no items exist yet, the empty state with the crossed-pencil pictogram is shown and the add row is ready.
5. Next step: Flow B.

Flow B — Adding a todo item

1. On the Todo List page, the owner types a task into the add field.
2. They activate the add control.
3. The new row snaps into the list with an unchecked checkbox, and the open count in the index rail increments.
4. The add field clears and stays focused.
5. Failure/recovery: if the input is empty or whitespace-only, nothing is created; if the save request fails, the item is not shown as saved and an inline message offers retry.
6. Next step: repeat for more items, or Flow C / Flow D.

Flow C — Marking an item complete (and undoing it)

1. On the Todo List page, the owner activates the checkbox on a row.
2. The orange tick draws on, the task text takes the completed strike treatment, the open count decrements and the done count increments.
3. Failure/recovery: if the update fails, the checkbox reverts and an inline message offers retry.
4. If the owner activates the same checkbox again, the item returns to incomplete and the counts reverse.
5. Next step: continue with other rows.

Flow D — Deleting a todo item

1. On the Todo List page, the owner activates the SCRAP stamp on a row.
2. The row is removed from the list and the relevant count updates.
3. Failure/recovery: if the delete request fails, the row stays in place and an inline message offers retry.
4. Next step: continue with the remaining rows.

Flow E — Returning to the list on the same device

1. The owner revisits the Todo List page (directly or via the Landing page).
2. The saved items load and render in creation order with their completion states intact, and the index rail shows the current open and done counts.
3. Failure/recovery: if loading fails, an inline error with a retry control replaces the list panel; retrying re-fetches the authoritative state.
4. Next step: resume Flow B, C, or D.

6. Visuals Colors and Theme

The creative direction is authoritative: Plain-talk task-keeping after Aaron Draplin — kraft, ink and one honest orange.

Palette (light mode)

Typography

• Headings: Alfa Slab One, weight 400 only, all-caps, tight leading 0.9, slightly negative tracking; oversized hero wordmark; section heads at 28–36px.
• Body and UI: Oswald at 400/500/600; micro-labels all-caps at 11–12px with 0.14em letter-spacing for field names, counts, and stamps.
• Scale: 1.333 modular — 72 / 56 / 40 / 28 / 18 / 16 / 12; hero display clamp(56px, 12vw, 148px).

Shape language

• Hard-edged panels with 2px ink borders; corner radius 4px maximum.
• Chunky checkbox squares with a hand-drawn-looking orange tick.
• Badge/stamp shapes: rounded-rectangle label tags and a circular count seal.
• No soft shadows, no glass, no pills — offset solid blocks of colour instead of drop shadows.

Layout

• Single asymmetric editorial column.
• Full-bleed kraft hero with the oversized wordmark left-aligned and an orange rule beneath it.
• Paper list panel spanning 8 of 12 columns, with a narrow ruled index rail on the right holding open/done counts as stamped numerals.
• Rows 64px tall with a hairline ink rule between them: checkbox left, task text centre, delete stamp right.
• At 375px the rail stacks under the list as a horizontal ruled strip.

Imagery

• No photography. Thick-line vector marks only: a hand-drawn checkmark, a circular DONE stamp, halftone dot texture at 6% opacity on the kraft ground, and a small crossed-pencil pictogram in the empty state — all drawn at the same 2.5px stroke weight.

Readability constraint: headlines, wordmarks, labels, numbers, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit; decoration may bleed, rotate, or overlap, but never covers readable text or a control.

7. Signature Design Concept

The public entry is a full-bleed kraft page with no card and no centred hero. The left two-thirds carries the wordmark TODO in Alfa Slab One at clamp(56px, 12vw, 148px), stacked on two lines, with a thick 8px orange rule running from the baseline out past the right edge of the viewport. Beneath it sits a single all-caps Oswald line: ONE LIST. NO CEREMONY. The right third holds a tilted paper panel (rotate -2deg) showing three sample ruled rows with one ticked in orange, bleeding off the bottom edge. A small circular orange seal with the open count sits at the seam between the two halves. The entry control is a hard-edged ink block with an all-caps Oswald label, placed in the left column under the tagline — never in the centre. Halftone dots at 6% opacity sit over the kraft ground. No gradient, no centred headline-plus-button composition.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the oversized TODO wordmark and the 8px orange rule that runs off the right viewport edge, with the tilted sample paper panel at the seam.
• Input → transformation → outcome thesis: on load, the orange rule draws outward from the wordmark baseline to the viewport edge, and the tilted sample panel settles into its -2deg position; the circular count seal presses in last. The outcome is a composed, sturdy first frame that reads as a working notebook cover, not an animated showreel.
• Motion vocabulary: mechanical and restrained — 90ms ease-out snaps, 120ms tick draw-on, 140ms stamp press-and-fade. No bounce, no spring, no looping decoration.
• Composed first frame: kraft ground with halftone texture, TODO wordmark left-aligned on two lines, orange rule beneath, tagline line, tilted paper panel on the right with three ruled rows and one orange tick, circular seal at the seam, entry control in the left column.
• Reduced-motion state: with prefers-reduced-motion, every element appears instantly in its final composed position — rule fully drawn, panel at -2deg, seal in place — with no transitions.

9. Non-Functional Requirements

• Simplicity (explicit): the todo list should be simple. No feature beyond add, view, complete, delete, and persistence is introduced; no settings, filters, tags, priorities, due dates, or sharing.
• Persistence (required_inference): todo items must survive page reloads and return visits on the same device, backed by the provisioned MariaDB database through the shared FastAPI backend.
• Responsive legibility (explicit, from the creative direction): readable text and controls stay whole and inside the viewport and their container at 375px, 768px, and 1280px.
• Accessibility (required_inference): checkboxes and the SCRAP stamp are operable by keyboard and expose accessible names; the orange tick is not the sole indicator of completion (the strike treatment and the done count also convey it).
• Reduced motion (explicit, from the creative direction): with prefers-reduced-motion, all motion becomes instant state change.
• Performance (required_inference): the list loads and renders promptly on a normal connection; interactions reflect optimistically with server confirmation and revert on failure.

10. Tech Stack

• Frontend: React application (provisioned frontend service).
• Backend: shared FastAPI process (provisioned backend service) exposing the todo-item API; new domain routes are added to this existing process rather than a new service.
• Database: MariaDB (provisioned database service) storing todo items.
• Fonts: Alfa Slab One and Oswald, loaded as web fonts.
• Containerization: Docker / docker-compose for the three provisioned services.

11. Assumptions and Constraints

• Assumption: "same device" persistence is satisfied by device/browser-scoped storage of the list in the application database, since the Planning Scope sets anonymous access on both pages and the source never asks for accounts. (required_inference)
• Assumption: a single shared list exists per device context; no multi-list, multi-user, or per-account separation is in scope. (required_inference)
• Constraint (explicit): the todo list should be simple — no adjacent task-management capabilities are added.
• Constraint (explicit, from the creative direction): the specified palette, fonts, surfaces, tone, and layout are preserved; the generic indigo/blue-on-white SaaS template is forbidden.
• Constraint (explicit, from the creative direction): readable text and controls are never cropped, clipped, or covered, even where decoration bleeds or rotates.
• Out of scope: accounts, sign-in, sharing, collaboration, notifications, due dates, priorities, tags, search, filtering, reordering, and editing of existing item text.

12. Glossary

• Todo Item — a single task entry with task text, a completion state, creation order, and a stable identifier.
• Todo List Owner — the single human user of the product; the only active persona.
• Open count — the number of todo items not yet marked complete, shown as a stamped numeral in the index rail.
• Done count — the number of todo items marked complete, shown as a stamped numeral in the index rail.
• Index rail — the narrow ruled column (stacked below the list at 375px) holding the open and done counts.
• SCRAP stamp — the all-caps delete control on each list row.
• Kraft ground — the #E8DECB page background carrying the halftone dot texture.