# Requirements: Todo web app (local)

> **Status: Accepted**  
> **Accepted by:** Michael  
> **Accepted on:** 2026-04-29

## Introduction

The Todo feature is a **single-page** web application that runs entirely in the user’s browser. Users manage a personal list of tasks: create items, mark them complete or incomplete, delete them, and **reorder** them. There is **no** backend server; all data is stored **locally** in the browser so that tasks and their order **survive** page refresh and normal browser restarts. This document states **what** the system must do; storage technology, component libraries, and drag-and-drop implementation are left to the design phase.

## Glossary

- **Todo_Web_App** — The single-page client application that implements this specification.
- **Todo_Item** — A single user-defined task: display text, a completion flag, and a **stable position in the list order** (see ordering requirements).
- **Local_Persistence** — The browser-local mechanism (exact technology unspecified here) that stores **Todo_Items** and their order on the user’s device.

## Requirements

### Requirement 1: Add a todo

**User story:** As a user, I want to add a new task with a short text description, so that I can track work I need to do.

#### Acceptance criteria

1. THE Todo_Web_App SHALL let the user submit a new **Todo_Item** with a text field (title or body—one primary text value per item).
2. THE Todo_Web_App SHALL NOT create a **Todo_Item** if the user’s text is empty or contains only whitespace after trimming; in that case it SHALL make the failure obvious (e.g. disable submit, inline message, or equivalent).
3. THE Todo_Web_App SHALL reject or cap overly long text so the UI remains usable; any maximum length SHALL be at least 500 characters after trim (exact limit and behavior for overflow are implementation-defined but MUST be defined in **design**).

### Requirement 2: Toggle completion

**User story:** As a user, I want to mark a task complete or incomplete, so that I can see what is done and what is still open.

#### Acceptance criteria

1. THE Todo_Web_App SHALL let the user change a **Todo_Item** between _completed_ and _not completed_ with a **single, repeatable** action (e.g. checkbox or toggle)—no separate “mark complete” vs “mark incomplete” command if a toggle suffices.
2. WHEN a **Todo_Item** is _completed_, THE Todo_Web_App SHALL show that state unambiguously in the list (e.g. strikethrough, icon, or similar).
3. WHEN the user uses the same control again on a _completed_ item, THE Todo_Web_App SHALL return that item to _not completed_.

### Requirement 3: Delete a todo

**User story:** As a user, I want to remove a task I no longer need, so that my list stays accurate.

#### Acceptance criteria

1. THE Todo_Web_App SHALL let the user delete any **Todo_Item** from the list.
2. WHEN a **Todo_Item** is deleted, THE Todo_Web_App SHALL no longer show it, and that item SHALL NOT reappear after a normal refresh unless it was re-created (see persistence requirements for durability semantics).

### Requirement 4: Reorder todos and persist order

**User story:** As a user, I want to change the order of my tasks, so that I can prioritize; that order should still be there after I reload the page.

#### Acceptance criteria

1. THE Todo_Web_App SHALL let the user **reorder** **Todo_Items** in the list using **direct manipulation** (drag-and-drop of a row, a drag handle, or an equivalent that moves items in the list).
2. WHEN reordering finishes, THE Todo_Web_App SHALL update the visible list to match the new order immediately.
3. THE **Local_Persistence** SHALL store order such that, after a full page reload, **Todo_Items** appear in the **same** relative order the user last established (for the same browser profile and storage).

### Requirement 5: List presentation, empty state, and single-page experience

**User story:** As a user, I want a simple one-screen app that always shows my todos clearly, or tells me when there are none.

#### Acceptance criteria

1. THE Todo_Web_App SHALL present the core experience on **one** primary view (single-page app); navigating away to other URLs or full-page routings is **out of scope** for the minimum feature (in-app dialogs or panels are allowed).
2. THE Todo_Web_App SHALL list all **Todo_Items** in their current order when at least one exists.
3. WHEN there are no **Todo_Items**, THE Todo_Web_App SHALL show an **empty state** (message or placeholder) that makes it clear the list is empty and that the user can add a task.
4. THE Todo_Web_App SHALL allow the user to perform add, complete/incomplete, delete, and reorder without requiring a network connection to a **custom backend** (see Requirement 6).

### Requirement 6: Local-only durability

**User story:** As a user, I want my tasks and their order to still be there after I close the tab or restart the browser, without signing in to a server.

#### Acceptance criteria

1. THE **Local_Persistence** SHALL retain **Todo_Items** and their order across **page refresh** in the same browser and origin.
2. THE **Local_Persistence** SHALL retain **Todo_Items** and their order across **normal application restart** of the browser (same user profile, same site data not cleared), without requiring a remote server.
3. THE product SHALL NOT depend on a **project-specific backend API** to store or sync todos; sync, accounts, and cloud backup are **out of scope** unless added in a later requirements pass.

## Open questions

_None_ — the maximum text length in **1.3** is bounded for design; exact UI for validation in **1.2** is left to design and implementation.