014: Mini Project I Finish

Learning outcomes

By the end of this lesson, you can refactor markup without changing intended content; find and fix broken links, heading hierarchies, labels, and image alternatives; use a conformance checker as diagnostic evidence; conduct a respectful independent review; and explain each semantic decision.

Prerequisites and retrieval

Bring 013's working site and acceptance criteria. Before editing, state the difference between “renders in my browser,” “conforming HTML,” and “accessible.” None implies the other two completely.

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

Finishing is a test-and-repair loop:

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

Do not rewrite a working site from scratch. Small fixes preserve intent and make regressions easier to spot. Review content and semantics before visual details. One missing </a> can distort much of the DOM; fix structural errors before interpreting later validator messages.

Baseline checklist

Record current page count and known limitations. Then check every 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.

Guided example: diagnose and refactor

Problem source:

html
<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.

Small repaired result:

html
<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 navigates, so it is an anchor. The positive tabindex disappears; source order governs focus. The heading reflects hierarchy. The alt is only correct if the screenshot conveys that result and nearby text does not already do so. If redundant, alt="" may be better. Review context, not just syntax.

After each fix, reload and retest the nearest behavior. After the batch, test all pages sharing copied navigation. Fixing one page does not update static siblings automatically.

Combine automated and manual review

No single checker can prove that HTML is good. Use different tools for different questions:

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?

Automated success is evidence, not proof. A page containing <img alt="image"> may pass a syntax checker and still have useless alternative text. A form can be valid HTML and still ask an ambiguous question. Review meaning as well as syntax.

Conformance workflow

Use the Nu HTML Checker by uploading/pasting each complete page or validating a deployed URL. Start with the first error; later errors may cascade. Common findings include stray end tags, disallowed nesting, duplicate IDs, missing required attributes, and obsolete features.

The checker is an evolving diagnostic tool, not certification. Zero reported errors does not prove correct alt text, hierarchy, keyboard operation, security, or WCAG conformance. Conversely, understand warnings before changing correct intentional code. Record:

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

Inspect the parsed DOM when source nesting seems correct visually. Browser error recovery may insert or move nodes. Compare View Source with Inspector.

Intermediate example: independent review protocol

Review a second site or a saved version without editing the original files. Spend ten minutes:

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.

Finding format:

text
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 code and impact, not its author. Record a question when intent is unclear, then reproduce the issue, fix it, or document why no change is needed. “I prefer another tag” is not a finding without semantic evidence.

Advanced optional extension: traceability and regression matrix

Map acceptance criteria to 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 refactoring shared navigation, run a page matrix instead of spot-checking Home. Static duplication creates regression risk. Future server-side templates can centralize it, but introducing tooling today would expand scope.

Keep the audit reproducible. Record the browser and checker date, the exact page or file, the test data, and the observed result. Screenshots can support a finding, but source excerpts and keyboard steps usually explain it better. When a defect is fixed, add a short prevention note: for example, “derive every nested path from the containing document” or “copy the navigation skeleton, then immediately update title, heading, and current state.” Prevention turns one repair into a maintainability improvement. If a finding is deferred, assign a reason and risk rather than silently removing 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

Prioritize blockers: inaccessible controls, keyboard traps, missing labels, broken navigation, and missing meaningful alternatives before minor maintainability issues. Test focus visibility, headings/landmarks, errors, zoom, and media alternatives. Independent review helps but does not replace testing with disabled users.

Search source/comments for secrets and private data, inspect external links and form endpoints, and use only fictional submissions. Confirm client validation is not presented as security. Recheck image sizes/dimensions, avoid unnecessary autoplay/scripts, and fix broken resources. A valid lean DOM aids reliability, but do not remove needed semantics for a metric.

Tiered exercises

Level 1: self-review

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

Level 2: full audit

Check all pages/links/headings/labels/alt, run Nu on each, keyboard-test one complete journey, and retest after fixes.

Level 3: independent review

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

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

Level 2: a complete audit artifact contains a row per page, all navigation and nested links exercised, heading outline recorded, image decision noted, labels clicked, invalid boundaries tested, and every Nu message resolved or explained. After fixes, repeat the journey because refactoring can regress paths/current state.

Level 3: strong findings use location, severity, reproduction/evidence, impact, minimal repair, and retest. Example high: different radio names; medium: duplicate current states; medium: 4 MB project image without matching purpose/dimensions. Residual risk should mention untested CSS contrast/reflow, production form server behavior/security, broader browser/AT combinations, and user testing.

Recap and exit questions

Finishing means systematic evidence, minimal refactoring, regression testing, and explainable choices. Validators catch authoring mistakes; human review catches 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 you can — reviewing your own code for defects is much harder than reviewing someone else's, because you already know what you meant to write. If nobody is available, put Rina's site aside for a day and come back to it cold; the delay does some of the same work.

Run the ten-minute independent-review protocol from this lesson on Rina's site specifically:

Keyboard journey: Home → menu → order form → submit.
Read only the headings out loud, 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 using the format from this lesson — location, severity, evidence, minimal fix — even if it feels like a small thing. A real example, from a site exactly 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." Notice that this finding is about maintainability, not a bug — reviews worth doing catch both kinds.