Semantic HTML & Accessibility: What I Learned Auditing My Own Portfolio

CLINTON HAMISI JONYANG — Wed, 21 Oct 2026 09:03:10 +0000

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.

DEV Community: CLINTON HAMISI JONYANG

Semantic HTML & Accessibility: What I Learned Auditing My Own Portfolio

What is semantic HTML (and why it matters)?

Before / After: A Real Snippet