When I built my first multi-page portfolio, I thought "if it looks right, it works." Then I ran Lighthouse and WAVE on my site — and realized looking right and being accessible are two different things.
Here's what I learned about semantic HTML, the accessibility issues I found, and how I fixed them.
What is semantic HTML (and why it matters)?
Semantic HTML means using the tag that describes what the content is — not just how it looks.
A <div> says nothing. A <nav> says "this is navigation." A <header> says "this is the top of the page." A <main> says "this is the primary content."
Why it matters:
- Screen readers use semantic tags to let users jump straight to the main content or navigation.
- Search engines understand your page structure better.
- Other developers (including future you) can read the code and instantly know what each block does.
- Accessibility tools like Lighthouse and WAVE can only help if your structure is meaningful.
In short: semantic HTML makes your site usable by more people, with less effort.
Before / After: A Real Snippet
Here's a block from an early draft of my site — pure <div> soup:
html
<div class="header">
<div class="logo">My Site</div>
<div class="nav">
<div class="nav-item">Home</div>
<div class="nav-item">About</div>
<div class="nav-item">Contact</div>
</div>
</div>
Here's a block re-written with good semantic tags:
<header>
<div class="logo">My Site</div>
<nav aria-label="Main navigation">
<ul>
<li><a href="index.html">Home</a></li>
<li><a href="about.html">About</a></li>
<li><a href="contact.html">Contact</a></li>
</ul>
</nav>
</header>
What changed:
<div class="header"> → <header>
<div class="nav"> → <nav>
<div class="nav-item"> → <li> with a real <a> link
Same visual result. Completely different meaning to a screen reader.
Accessibility Issues I Found (and Fixed)
>Running Lighthouse and WAVE on my portfolio surfaced three problems:
1. Missing alt text on images
Issue: My profile image had no alt attribute. Screen readers announced it as just "image."
Fix:
<!-- Before -->
<img src="images/profile.jpg">
<!-- After -->
<img src="images/profile.jpg" alt="Clinton Hamisi, founder of BlankSlate Blueprint Core">
Now the image actually describes itself to anyone who can't see it.
2. Missing lang attribute on <html>
Issue: Without lang="en", screen readers may pronounce English text with the wrong accent or use the wrong dictionary.
Fix:
<!-- Before -->
<html>
<!-- After -->
<html lang="en">
A one-word fix with a big impact.
3. Non-descriptive link text
Issue: One link simply said "click here." Out of context, it's meaningless — especially for someone tabbing through links with a screen reader.
Fix:
<!-- Before -->
<a href="https://github.com">click here</a>
<!-- After -->
<a href="https://github.com">Visit my GitHub profile</a>
The new text tells the user where they're going before they click.
What I'd Tell Anyone Starting Out
You don't need a perfect site. You need a clear structure and honest labels:
>Use <header>, <nav>, <main>, <article>, <aside>, <footer> — they're free and they help everyone.
>Add alt text to every image (describe what it shows, not what it is).
>Always set lang on <html>.
>Write link text that makes sense on its own.
A few small changes turned my portfolio from "looks fine" to actually usable.
See It Live
I deployed the updated portfolio on GitHub Pages:
🔗 hamisi254iyf.github.io/iyf-s12-week-01-Hamisi254IYF
The full accessibility report is in the repo, and every page in the site now passes Lighthouse's accessibility audit with a perfect score.
If you're building your first site — run Lighthouse on it today. You'll learn more in 5 minutes than in a week of guessing.
Top comments (0)