templates.SimpleTodo/SPEC.md

Simple Todo List — product specification

This is the contract the project is built against. It is written for the agent that scaffolds the repository, but it doubles as the human-readable brief: every requirement below is meant to be implementable and verifiable.

This is the minimal demo template. The goal is the smallest website that is genuinely useful, so the spec is deliberately short and the non-goals matter as much as the goals.

Values in angle brackets (<Project name>, <accent>) come from the project-creation dialog and are recorded in the project record (.w4c/project.json → fields); replace them as you read.

1. Goal

A single static page that manages a todo list — add a todo, mark it done or undone, delete it, clear the completed ones, filter by all / active / done — and remembers the list in the browser between visits. It must be usable the moment it is served: no install step, no build step, no backend and no account. <Project name> is the page title; <accent> is the single accent colour.

Non-goals (do not build)

• No backend, API, database or authentication.
• No framework, package manager, bundler or third-party runtime — plain HTML, CSS and JavaScript.
• No accounts, sharing, sync between devices or server persistence.
• No service worker / offline caching, no analytics, no ads.
• No admin panel, control panel, workflows or database layer.

2. The screen

One route, / (the static index.html). It contains:

• a header with <Project name>;
• a composer — a labelled text input plus an Add control (Enter also submits);
• a list of todos, each row: a checkbox/toggle ("done"), the title, a Delete control (visible or on row hover/focus — always reachable by keyboard);
• a footer with the count of remaining active todos, the filters (All / Active / Done) and a Clear completed action shown only when at least one todo is done;
• an explicit empty state when there are no todos (and a distinct message when the filter has no matches), and a hidden/disabled Delete/Checkbox state that never leaves a row inaccessible.

No routing beyond the single page; /404 is not required.

3. Data model

One entity, persisted as a JSON array in localStorage:

• Todo — id (unique, e.g. a stringified timestamp or crypto.randomUUID()), title (non-empty, trimmed), done (boolean), createdAt (ISO timestamp).

Storage contract: a single documented key holds the array (e.g. simple-todo.items). A missing, empty or unparseable value is treated as an empty list — never throw. Unknown fields are ignored; a malformed stored item is dropped, not rendered as a broken row. The filter selection is UI state and does not need to persist (persisting just the filter is optional).

4. Key flows

1. Add. The user types a non-empty title and presses Add (or Enter): the todo appears at the top of the list, the input clears and refocuses. Whitespace-only input is rejected (the Add control is disabled and the input stays unchanged).
2. Toggle. Clicking the checkbox / row toggles done; the title gets a struck-through done style and the remaining count updates.
3. Delete. The Delete control removes the row; the list and the empty state update immediately.
4. Clear completed. Shown only when at least one todo is done; removes every done todo after the built-in confirmation (a native confirm() is acceptable) and updates the list.
5. Filter. All / Active / Done switches the visible rows; the active filter is visibly marked and exposed to assistive tech (aria-pressed or equivalent). The footer count reflects the active todos regardless of the filter.
6. Persist. Every mutation writes the list to localStorage; reloading the page restores the list exactly (order, done state, titles) and the correct remaining count.

5. Functional requirements

• Input validation: titles are trimmed; empty/whitespace titles are never added; long titles wrap instead of overflowing; a sensible maximum is enforced (e.g. 200 characters, hinted to the user) rather than silently truncating stored data.
• Rendering: the list is rendered from the stored array (a single render() function is enough); the DOM never accumulates stale rows across re-renders.
• Counts: the "X active" count updates on every add / toggle / delete / clear / filter change.
• Keyboard: everything the mouse can do is reachable and operable with the keyboard; focus is visible and focus order follows the visual order. The composer supports Enter to add.
• Safe text: todo titles are inserted as text, never as HTML (no innerHTML with user input), so a title like <img src=x onerror=alert(1)> renders as literal text.
• No network: the page makes no requests; it works when opened directly from the filesystem.

6. Non-functional requirements

• Dependency-free: plain HTML + CSS + JavaScript. ES modules or one <script> are both fine; a package.json / bundler is not. The page must run from file:// and from a static server.
• Performance: a single small page; first render well under 1 s on a normal machine; no render-blocking third-party assets.
• Responsive: usable from 360px wide up to desktop; no horizontal scroll at 390×844.
• Accessibility (AA): semantic landmarks (header/main/footer), a real <label> for the composer input, the checkbox as an accessible control (or a button with aria-pressed), ≥ AA contrast for the <accent> colour and the done style, visible focus.
• Resilience: corrupt/empty storage degrades to an empty list; no unhandled errors in the console during normal use.
• Security: no secrets; user input is rendered as text only.

7. Acceptance criteria (definition of done)

• The project is a static site: no package.json, no bundler, no third-party runtime, no network calls.
• Served at /, the page loads with no console errors and shows the empty state on a fresh browser.
• Adding, toggling, deleting and clearing todos all work; the remaining count is always correct.
• The All / Active / Done filter works, marks the active filter and shows a distinct no-match state.
• Reloading restores the list exactly from localStorage; a corrupted stored value degrades to an empty list instead of throwing.
• A title containing HTML is rendered as literal text (no injection).
• Whitespace-only titles cannot be added; long titles wrap and do not overflow.
• Everything is operable by keyboard alone, with visible focus and AA contrast.
• Usable at 390×844 with no horizontal scroll.
• The README quickstart (how to serve it, how to use it) works on a clean clone.
• The dev server (template devServer section) serves the page at its port.

8. Suggested build order

This is a small project — keep it top-down and verify each step before the next:

1. Skeleton — index.html with the header, composer, list and footer, styled with the accent colour; empty state visible. Serve it and confirm it loads.
2. Model + storage — the Todo shape, load/save to localStorage (with the corrupt-value fallback), and rendering the list from the stored array.
3. Interactions — add, toggle, delete, clear-completed, filters, counts, keyboard support.
4. Polish + quality — responsive layout, accessibility pass, injection-safe rendering, README quickstart, and walk every acceptance box.