Published and updated 31 July 2026 · Start Here
Published and updated 31 July 2026 · Start Here
Start Here: Learn the System and Ship Your First Page connects the essential decisions in this stage of frontend engineering. You will learn each browser or framework model from first principles, apply it to the progressive Learning Atlas product, diagnose a realistic failure from evidence, and direct an AI collaborator with explicit constraints. The goal is independent judgment, not memorized syntax.
You will advance a small Learning Atlas page. By the end, you can explain every topic in this chapter, implement one focused slice per topic, adapt those slices under new constraints, and defend the result with browser evidence, strict types, accessibility checks, security boundaries, and a production build.
Bring forward learning-atlas/index.html and learning-atlas/README.md and the verification notes from the preceding chapter. Create a narrow Git branch, read the repository rules, and inspect existing changes before editing. When a tool or file is introduced for the first time, its purpose is explained before its syntax.
Use these project-orientation commands:
Before beginning Start Here: Learn the System and Ship Your First Page, stop if the working tree contains files you do not understand. Do not delete, reset, or rewrite another person's work to make the lesson cleaner.
Treat every tool as one station in a visible delivery line: the browser displays, the editor changes, the terminal runs commands, Git records decisions, and the AI collaborator proposes work that you inspect. The topics below are ordered because each creates evidence needed by the next. Experienced readers may jump to a topic, but should still complete its failure investigation and adaptation task.
The book is a practice system: read a mental model, predict behavior, build a narrow slice, challenge it, and keep evidence. Reading in order builds one product; experienced readers can enter by section and still complete each chapter's verification loop.
The current artifact for about this book and how to use it is learning-atlas/README.md. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: A learner reads chapters passively, copies every example, and reaches React without being able to explain an HTTP request or recover a Git change.
Evidence to collect: Ask the learner to rebuild the last exercise without the page, narrate each decision, and show the Git diff plus browser evidence.
Minimal repair rule: For about this book and how to use it, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Design a two-week study rhythm that includes building, recall, failure practice, and a weekly evidence review.
A URL tells the browser where to send an HTTP request. The server returns bytes and metadata; the browser parses HTML into a document, applies CSS, runs allowed JavaScript, fetches dependencies, and turns the result into pixels and an accessibility tree.
The current artifact for how the web works: browser, server, url, http, html, css, and javascript is learning-atlas/request.txt. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: A page works from a local file but fails through a server because its script path resolves against a different URL and returns an HTML 404 response.
Evidence to collect: Inspect the Network request URL, status, Content-Type, response body, initiator, and Console parse error before changing code.
Minimal repair rule: For how the web works: browser, server, url, http, html, css, and javascript, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Draw the complete request sequence for a page with one stylesheet, one module, and one API request, including one failure response.
The terminal starts processes in a working directory; Node.js runs JavaScript outside the browser; npm installs and invokes project tools; the editor changes files; Git records versions; DevTools observes the running interface. Each answers a different debugging question.
The current artifact for your toolchain: terminal, node.js, npm, editor, git, and browser devtools is terminal. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: The developer installs packages in the parent directory, so the command succeeds while the application still cannot resolve the dependency.
Evidence to collect: Compare pwd, the nearest package.json, npm prefix, Git root, running process output, and the browser's loaded source path.
Minimal repair rule: For your toolchain: terminal, node.js, npm, editor, git, and browser devtools, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Start from an empty directory, initialize a project, explain every created file, and prove which process is serving the browser response.
Safe AI pairing divides responsibility explicitly. The human owns intent, permissions, secrets, destructive actions, architecture, and acceptance; the agent may research, propose, edit bounded files, and run approved checks while exposing assumptions and evidence.
The current artifact for the ai pairing pact: context, constraints, verification, and safe autonomy is learning-atlas/specs/first-page.md. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: A vague request produces a polished rewrite that deletes a user's uncommitted change and adds a dependency the repository forbids.
Evidence to collect: Compare the request, repository rules, pre-change status, touched-file list, dependency diff, and criterion-to-evidence report.
Minimal repair rule: For the ai pairing pact: context, constraints, verification, and safe autonomy, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Write an autonomy ladder for read-only inspection, local edits, package installation, data migration, deployment, and deletion.
A first page needs a valid document, one clear purpose, semantic content, responsive viewport behavior, and a reversible history entry. A commit should capture one understood outcome and a message that explains why the change belongs together.
The current artifact for build your first page and publish the first commit is learning-atlas/index.html. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: The browser displays a page, but the repository contains no index.html because the file was saved outside the Git root.
Evidence to collect: Use the Elements panel to identify the loaded document URL, then compare pwd, git status, git ls-files, and the editor's absolute file path.
Minimal repair rule: For build your first page and publish the first commit, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Add a second section and focusable link, validate the document, test at 320 pixels, and create a commit whose diff contains only that outcome.
Goal: Advance a small Learning Atlas page through one learning outcome at a time while keeping the implementation understandable and reversible.
Context to attach: the current start here outcome, the product brief, repository rules, package versions, relevant files and callers, shared types or tokens, the current Git diff, and the latest observed failure or command output.
Constraints: while advancing a small Learning Atlas page, preserve concurrent work; use semantic HTML and strict TypeScript; keep Server Components as the default in Next.js; validate untrusted data on the server; do not expose secrets; include loading, empty, error, success, disabled, and partial states when relevant; make one bounded change.
Acceptance criteria: the start here adaptation works from 320 pixels upward; keyboard and focus behavior are complete; color is not the only signal; authorization and validation are enforced at authoritative boundaries; the relevant type, lint, build, and browser checks pass.
Reusable prompt:
We are implementing one outcome from “Start Here: Learn the System and Ship Your First Page” in the Learning Atlas. Read the attached repository rules, outcome text, relevant files, current diff, and verification evidence. Restate the user-visible result, source of truth, trust boundary, valid states, and unknowns. Propose the smallest reversible vertical slice. Implement only that slice. Then report the exact diff, criterion-to-evidence mapping, remaining risks, and the next discriminating check. Stop before dependency installation, destructive action, public-contract change, authentication decision, or deployment unless explicitly authorized.
For Start Here: Learn the System and Ship Your First Page, inspect the response without relying on its summary. Read every changed line, compare it with the actual source of truth, and reproduce the evidence yourself. Reject unexplained assertions, broad client boundaries, missing states, invented APIs, suppressed errors, or tests that merely restate implementation details.
A first-time learner runs a command from the wrong directory, edits a different file than the browser serves, and commits an unrelated change. Trace cwd, server URL, file path, Git root, and diff until all five agree. Write exact reproduction steps and expected versus observed behavior. Follow the value across every relevant boundary until you find the first contradiction.
Within the follow stage of Start Here: Learn the System and Ship Your First Page, change one cause, not several symptoms. Rerun the original reproduction, one adjacent failure case, keyboard navigation, and the focused static checks. The lab is complete only when you can explain why the repair works and which regression check would have failed before it.
Run the scripts that this project actually defines:
If your learning project later defines a test script, run it as an additional gate; do not report tests as passing when no test command exists. In the browser, open the page locally, describe what changed in plain English, and inspect the Git diff before committing. Repeat the primary journey at 320, 768, and wide desktop widths, at 200% zoom, in both themes, by keyboard, and with reduced motion. For networked work, simulate slow, malformed, unauthorized, empty, and failed responses.
Close Start Here: Learn the System and Ship Your First Page and draw its models from memory. Pick two outcomes and explain how a decision in the first can cause a failure in the second. Then complete three levels of practice:
You have treated start here as a connected engineering system rather than isolated syntax. The durable result is not the example code; it is the ability to predict behavior, expose assumptions, collect evidence, bound AI work, and repair the first broken boundary. Carry the product files and evidence log into the next stage.