014: Mini Project I Finish

Learning outcomes

By the end of this lesson, you should be able to refactor markup without changing the content the page is meant to deliver. You should also be able to find and repair broken links, heading hierarchies, labels, and image alternatives; use a conformance checker as evidence while diagnosing a problem; carry out a respectful independent review; and explain the reasoning behind each semantic decision.

Prerequisites and retrieval

Start with the working site and acceptance criteria from lesson 013. Before you touch the files, explain the difference between “renders in my browser,” “conforming HTML,” and “accessible.” Those descriptions overlap, but none of them guarantees the other two.

Terminology

Refactor: improve internal structure without intentionally changing external behavior/content (course term).
Defect: an observable mismatch from a requirement (course term).
Regression: a previously working behavior broken by a change (course term).
Audit: Systematic evaluation against defined criteria, with documented evidence. — Source: W3C WCAG-EM Overview
Finding: evidence-based review item with location, impact, and recommended fix (course term).
False positive: tool-reported concern that does not apply after human analysis (course term).
Independent review: systematic examination of decisions and behavior using evidence (course term).
Conformance: Meeting the normative requirements stated by an applicable specification. — Source: WHATWG: Conformance requirements
Severity: prioritization based on user impact and reach (course term).
Conformance (official): “Meeting the normative requirements of a specification.” — Source: WHATWG: Conformance requirements
HTML validator (Nu): “A conformance checker that reports violations of authoring requirements.” — Source: Nu HTML Checker — About
Audit (WCAG-EM): “Systematic evaluation of a website against WCAG, with defined scope and methodology.” — Source: WCAG-EM Overview

Mental model: inspect systems, not cosmetics

Treat finishing as a test-and-repair loop rather than a final visual polish pass:

baseline -> inspect -> reproduce -> smallest fix -> retest locally
         -> retest related pages -> validate -> explain

Do not replace a working site wholesale. Small, isolated fixes protect the original intent and make regressions easier to recognize. Start with content and semantics, then move to visual details. A missing </a>, for example, can reshape a large part of the DOM, so repair structural errors before drawing conclusions from validator messages that appear later.

Baseline checklist

First record the current page count and any known limitations. Then run through every page, not just the home page:

doctype, correct lang, charset, viewport, descriptive unique title;
one visible main, page-specific h1, logical heading hierarchy;
consistent navigation, correct aria-current, meaningful link text;
all internal, nested, fragment, email, and telephone links;
semantic header/nav/main/section/article/aside/footer choices;
images loaded, real dimensions, context-appropriate alt, no duplication;
tables have caption, headers, scopes, logical grid;
form controls have unique IDs, matching visible labels, names, grouping, instructions, appropriate types/autocomplete/constraints;
links navigate, buttons act, keyboard order is meaningful, focus visible;
no obsolete elements/attributes, layout tables, spacing breaks, positive tabindex, duplicate native roles, secrets, or unnecessary personal data;
checker results read and resolved; known residual limitations documented.

This baseline gives you something to compare against. It also prevents a successful fix on one page from hiding the same defect in a copied sibling.

Guided example: diagnose and refactor

Here is a deliberately flawed fragment. Read it as a reviewer: identify the observable problems before changing the markup.

Problem source:

<div class="main">
  <h1>Portfolio</h1>
  <h4>Projects</h4>
  <img src="images/weather-project.webp" alt="image">
  <p><a href="project/weather.html">Click here</a></p>
  <div role="button" tabindex="1">Contact</div>
  <label>Email</label>
  <input type="email" name="email">
</div>

Findings:

Generic wrapper hides the dominant region.
Heading jumps from h1 to h4 for apparent size.
Alt does not replace image purpose and dimensions are absent.
Path likely mismatches projects/; link text is vague.
Contact navigation is a fake button with positive tabindex.
Label has no programmatic association; input lacks ID/autocomplete.

The smallest repaired result addresses those findings without redesigning the page:

<main>
  <h1>Portfolio</h1>
  <section>
    <h2>Projects</h2>
    <img
      src="images/weather-project.webp"
      alt="Weather summary showing Chennai at 31 degrees Celsius and cloudy"
      width="1440"
      height="900">
    <p><a href="projects/weather.html">Weather project details</a></p>
  </section>
  <p><a href="contact.html">Contact Asha</a></p>
  <p>
    <label for="email">Email</label>
    <input type="email" id="email" name="email" autocomplete="email">
  </p>
</main>

Contact performs navigation, so an anchor is the appropriate element. Removing the positive tabindex lets source order determine the focus order. The heading now expresses the document hierarchy instead of choosing a heading level for its default size. The alternative text is right only if the screenshot communicates that result and nearby text does not already communicate it. If the image is redundant, alt="" may be the better choice. Semantics depend on context, not syntax alone.

Reload and retest the nearest behavior after each change. Once the batch is complete, test every page that shares the copied navigation. Fixing one static page does not update its siblings automatically.

Combine automated and manual review

No checker can establish on its own that an HTML page is good. Each tool answers a different question:

Conformance checker: Is the source valid according to HTML's authoring rules?
Link check: Do local and external destinations resolve as expected?
Browser DevTools: Did the browser repair or reinterpret the source into a different DOM?
Keyboard pass: Can interactive content be reached and used in a sensible order?
Accessibility inspection: Are names, roles, states, headings, and landmarks exposed as intended?
Human content review: Are headings, labels, link text, alternative text, and metadata actually meaningful?

An automated pass is evidence, not proof. <img alt="image"> can satisfy a syntax checker while giving a screen-reader user no useful description. A form can conform to HTML and still ask an ambiguous question. Evaluate meaning and operation alongside syntax.

Conformance workflow

Use the Nu HTML Checker by uploading or pasting each complete page, or by validating a deployed URL. Begin with the first error. Later messages may be consequences of that initial structural problem. Typical findings include stray end tags, disallowed nesting, duplicate IDs, missing required attributes, and obsolete features.

Nu is an evolving diagnostic tool, not a certification service. Zero errors do not prove that alternative text, hierarchy, keyboard operation, security, or WCAG conformance is correct. The reverse also matters: understand a warning before changing code that is intentionally correct. Capture the investigation in a form like this:

Page | message | source line | root cause | fix | retest

When the source appears correctly nested but the browser behaves differently, inspect the parsed DOM. Error recovery can insert or move nodes. Compare View Source with the Inspector so you know whether you are looking at the authored document or the browser's repaired tree.

Intermediate example: independent review protocol

Review a second site or a saved version without editing the original files. Give yourself ten minutes and follow the same evidence-first process:

Complete one keyboard journey: Home -> project -> Contact -> form.
Read titles, headings, landmarks, and link names.
Disable/fail images mentally or practically and assess alternatives.
Click labels and test one valid/invalid submission.
Check one nested relative path and one fragment.
Run one page through Nu.
Write up to three high-value findings.

Use a finding format that lets another developer reproduce and repair the problem:

High - contact.html, Reply preference:
Radio buttons use different names, so both can be selected.
This contradicts the single-choice question and submits ambiguous data.
Give both radios name="reply", retain unique IDs/values, then keyboard-test.

Review the code and its impact, never its author. If intent is unclear, record a question, reproduce the behavior, and either fix it or document why no change is required. “I prefer another tag” is not a finding unless you can connect it to semantic evidence.

Advanced optional extension: traceability and regression matrix

Map each acceptance criterion to observable evidence:

Requirement	Evidence
navigation works	link journey on every page/path
hierarchy logical	text outline + headings inspection
form operable	keyboard/label/invalid matrix
conforming	saved Nu results reviewed
media appropriate	alt decision + dimensions/network check

After changing shared navigation, run a page matrix rather than spot-checking Home. Static duplication is a regression risk. Server-side templates could centralize the navigation later, but introducing that tooling now would expand the scope of this finish.

Keep the audit reproducible. Record the browser and checker date, exact page or file, test data, and observed result. Screenshots can support a finding, but source excerpts and keyboard steps generally explain it more clearly. When you fix a defect, add a short prevention note, such as “derive every nested path from the containing document” or “copy the navigation skeleton, then immediately update title, heading, and current state.” That turns one repair into a maintainability improvement. If a finding is deferred, record the reason and risk instead of quietly dropping it from the checklist.

Common mistakes and debugging

Changing content and structure simultaneously: isolate changes where possible.
Fixing validator messages bottom-up: repair earliest structural cause first.
Silencing warnings without understanding: document the decision.
Alt judged without context: compare image, caption, and nearby prose.
Current state copied everywhere: exactly one correct primary link per page.
Only mouse tested: perform full keyboard journeys.
Feedback based on taste: report reproducible impact and the relevant criterion.
Zero errors called accessible: state testing limits.
Unrelated redesign during finish: defer visual scope and protect working behavior.

Accessibility, security, and performance

Deal with blockers first: inaccessible controls, keyboard traps, missing labels, broken navigation, and missing meaningful alternatives matter before minor maintainability concerns. Check focus visibility, headings and landmarks, error states, zoom, and media alternatives. An independent review is useful, but it does not replace testing with disabled users.

Search source and comments for secrets or private data. Inspect external links and form endpoints, and submit only fictional data. Client-side validation improves feedback; do not present it as a security boundary. Recheck image sizes and dimensions, avoid unnecessary autoplay and scripts, and repair broken resources. A valid, lean DOM can improve reliability, but never remove required semantics just to improve a metric.

Tiered exercises

Level 1: self-review

Run the baseline checklist on Home. Record evidence and fix at least three issues using the smallest changes that address them.

Level 2: full audit

Check every page, link, heading, label, and alternative text; run Nu on each page; keyboard-test one complete journey; and repeat the relevant tests after fixes.

Level 3: independent review

Review a second site or saved version, write three findings ordered by severity, apply fixes with evidence, and provide a residual-risk statement.

Level 1: use the guided defect list and repaired snippet. Each change maps to semantics, path, accessible name, focus, or label association rather than visual preference.

Level 2: a complete audit artifact has one row per page, exercises all navigation and nested links, records the heading outline, notes each image decision, includes clicked labels and invalid boundaries, and resolves or explains every Nu message. Repeat the journey after fixing the pages because refactoring can regress paths or current state.

Level 3: strong findings include location, severity, reproduction or evidence, impact, minimal repair, and retest. Examples include different radio names as a high finding, duplicate current states as a medium finding, and a 4 MB project image without matching purpose or dimensions as a medium finding. Residual risk should mention untested CSS contrast and reflow, production form server behavior and security, broader browser and assistive-technology combinations, and user testing.

Recap and exit questions

Finishing is a disciplined loop of evidence, minimal refactoring, regression testing, and explainable choices. Validators expose authoring mistakes; human review is what evaluates meaning and operation.

Why fix the first parser error first?
What makes review feedback actionable?
Why must copied navigation be tested page by page?
What does zero checker errors prove and not prove?
Which unresolved risks should be documented?

Try it with your own example

Trade sites with a classmate or friend if possible. Reviewing your own code for defects is harder than reviewing someone else’s because you already know what you meant to write. If nobody is available, set Rina’s site aside for a day and return to it without context; the delay creates some of the same distance.

Run this lesson’s ten-minute independent-review protocol specifically on Rina’s site:

Keyboard journey: Home → menu → order form → submit.
Read only the headings aloud, in order. Do they summarize the site the way Asha’s did in lesson 003?
Mentally fail every image. Does the storefront photo’s alt, written back in lesson 005, still tell a first-time visitor where to find the shop?
Submit the cake-order form once validly and once with a required field empty.
Run index.html and order.html through the Nu checker.

Write down one finding in this lesson’s format: location, severity, evidence, and minimal fix. It can be small. Here is a realistic maintainability finding from a site like this one: “Medium — order.html, size fieldset: only the 6-inch radio has required. HTML behavior makes this technically sufficient, but a reviewer who skims the source might assume the 8-inch option is optional and remove required later during a refactor. Add a one-line comment or apply required to both for clarity, then retest with keyboard-only submission.” That is a maintainability concern rather than a current bug, and a useful review catches both kinds.