Workshop: build a small website

Back to the Codex learning hub

Goal and starting point

Lessons and resources mentioned here: Codex basics

Step 1: Prepare an empty workspace and reference

Download the Small Steps materials, extract them and keep expected in a separate reference folder. Start this lesson in a new website-lab with brief.md; do not mix in start or broken, which are controlled exercises for other lessons. expected contains five code files for comparison if you get stuck. Check node --version in your workspace terminal, then py -3 --version on Windows or python3 --version on macOS/Linux. Resolve missing commands using installation and Terminal paths first.

Windows, macOS and Linux use the same HTML/CSS/JavaScript. Open website-lab in Codex desktop, CLI or IDE: choose the folder in desktop, cd into it before codex in CLI, or open it as the IDE project. A phone can follow a computer task, but files and preview remain on the execution host; the phone's 127.0.0.1 is not your computer. Do responsive checks on the computer before considering any public network exposure for a phone demo.

Step 2: Specify the deliverable and acceptance criteria

Save the following as brief.md. English UI labels match the shared reference so all five language editions can verify the same buttons. Viewing added tasks supplies reading and toggling completion supplies updating, so the exercise covers all four CRUD operations without accounts, sync or collaboration. Define not only appearance, but corrupt-data behavior, blank input and keyboard use.

# Small Steps website brief
Build a local todo website using HTML, CSS and JavaScript only.

## Files
- index.html: accessible page and form
- style.css: responsive layout
- core.mjs: immutable data functions
- app.js: DOM events and localStorage
- core.test.mjs: Node built-in tests

## Data contract
- Task: {id: string, title: string, completed: boolean}
- Trim titles; accept 1 to 100 non-blank characters. IDs must be unique.
- Export addTask(tasks, title, id), toggleTask(tasks, id), removeTask(tasks, id),
  visibleTasks(tasks, filter), decodeTasks(raw), encodeTasks(tasks).
- Filters: all, active, completed. Missing toggle/delete IDs leave data unchanged.
- Store {version: 1, tasks: [...]} under mokaair-codex-todo-v1.
- Invalid stored data must remain untouched; warn and allow temporary work.

## Interface and acceptance
- Labels: New task, Add task, Show, All tasks, Active, Completed, Delete.
- Show active and total counts, including when a filter is selected.
- Add, toggle, delete, filter and reload must work.
- Render task text as text, not HTML.
- Visible keyboard focus; preserve sensible focus after list updates.
- Fit 360px, 390px and 1280px viewports without page overflow.
- Include an About this exercise disclosure with a Reset practice data button.
- Reset practice data removes only this app's storage key.
- No dependencies, account, backend, analytics or external requests.

## Delivery
Explain changes, run node --test core.test.mjs, and list actual browser checks.
Do not claim checks that were not run. Do not publish or deploy.

Step 3: Review the design, then implement in stages

Use Plan mode to read brief.md and propose responsibilities for the five files, data flow and acceptance checks. Ensure core.mjs does not access the DOM, while app.js handles controls/storage, without frameworks or extra services. Add missing corrupt-data or recovery behavior before switching to implementation. Split implementation into data/tests and UI/interactions, requiring actual changes and unverified items after each stage.

Implement core.mjs and core.test.mjs from the approved brief.md contract.
Keep all data operations immutable. Test empty and long titles, Unicode,
duplicate IDs, filters, missing IDs, storage round trips and invalid storage.
Run node --test core.test.mjs and report the command, result and remaining work.
Do not change the brief, publish anything or build the UI in this stage.

Implement index.html, style.css and app.js using the tested core.mjs.
Follow the UI, storage, accessibility and responsive criteria in brief.md.
Do not weaken the data tests to accommodate UI bugs.
Run the data tests again. Give local preview instructions and list which
browser interactions you actually verified and which still need verification.

After each stage, inspect files and run tests yourself. The reference core.test.mjs has three top-level tests with several assertions; generated test counts may differ, so do not compare counts alone. Implementation and tests can share the same mistaken assumption, which is why the independent UI checklist follows. If stuck, compare the relevant expected file and understand the difference before overwriting any unsaved work. Consult Git and recovery before reverting.

Step 4: Preview the same folder

node --test core.test.mjs
py -3 -m http.server 4173 --bind 127.0.0.1

node --test core.test.mjs
python3 -m http.server 4173 --bind 127.0.0.1

Open http://127.0.0.1:4173 and leave that terminal running; use another for commands. If the port is occupied, identify whether it is your own practice server before stopping anything. If choosing a free port, update both the URL and verification record. Double-clicking HTML uses file URLs that can restrict ES modules. If the wrong version appears, inspect the served folder, URL and app.js network response before asking Codex to rewrite the site.

Step 5: Verify behavior and layout

Expand About this exercise, confirm all tasks are disposable fictional data, then use Reset practice data to clear only this app's key. Select All tasks under Show, confirm 0 active / 0 total, then add Read and Build, and complete Read. All tasks shows two, Active only Build, Completed only Read, with 1 active / 2 total. Reload and confirm persistence; return to All tasks and delete Read, leaving Build. Continue with the table instead of accepting a single home-page screenshot.

Responsive emulation is not a physical iOS/Android test. Attached Windows/Edge reference images do not prove your generated result.

<img src=x>

Step 6: Corrupt data, fix and deliver

Perform the advanced check only on the local fictional page. Save needed test records, open browser developer tools → Storage/Application → Local Storage and select the current 127.0.0.1 origin and port. Change mokaair-codex-todo-v1 to bad-json and reload. Expect a warning; add a temporary task and verify stored data remains bad-json rather than being silently overwritten. Use Reset practice data to remove only that key, then add and reload a task to confirm recovery. Do not clear all data for other sites.

Before handing over, start with cleared fictional data and follow the sequence below, keeping expected and observed columns separate. Observe your own page even when using the reference implementation. Counts use all tasks while filtering, which catches accidental counting of the visible subset. Leave browser checks unverified when preview is unavailable.

# Website handoff
Root / source version:
Node test command / exit status:
Browser / version / viewport / date:

| Step | Expected active / total | Observed |
| --- | --- | --- |
| Reset fictional practice data; select All tasks | 0 / 0 | |
| Add Read, then Build | 2 / 2 | |
| Complete Read | 1 / 2 | |
| Select Active; only Build visible | 1 / 2 | |
| Select Completed; only Read visible | 1 / 2 | |
| Select All tasks, delete Read | 1 / 1 | |

Input/storage recovery evidence:
Keyboard and narrow-layout evidence:
Actual changed files:
Unverified requirements:
How to restart / restore:

When acceptance fails, report exact input, actions, expected and actual values. Ask Codex to fix the relevant layer and rerun affected checks using the Bug workflow. Deliver the brief, five files, Node test record, wide/narrow screenshots, untested platforms and recovery method. Stop the server with Ctrl+C in its original terminal. Ask for restart instructions in the Handoff format. Frameworks, a backend or public hosting require a separate explicit scope; a visible local page is not a deployment.

Back to the Codex learning hub

Read the full description

Brief to HTML / CSS to Browser checks

• AI tools
• Tutorials
• Codex