When I started building my portfolio, I treated HTML like a container for CSS. Everything was a <div>. It worked, the page looked fine, and I moved on.
Then I ran an accessibility audit.
Users who rely on screen readers, keyboard navigation, or translation tools were getting a broken experience — and I hadn't noticed because I could see the page fine. After fixing the issues below, my portfolio became much more usable for assistive technology.
This is what I learned.
What Is Semantic HTML?
Semantic HTML means using the element that describes what the content is, not just how it looks.
A <nav> is navigation. A <button> is clickable. An <h1> is the page's main heading. Screen readers, search engines, and assistive tools rely on these elements to understand your page. When everything is a <div>, that meaning disappears.
Here's the same navigation built two ways:
Before — non-semantic:
html
<div class="nav">
<div class="link"><a href="/">Home</a></div>
<div class="link"><a href="/about">About</a></div>
</div>
After — semantic:
html
<nav aria-label="Main">
<ul>
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
</nav>
Same visual result. Completely different experience for assistive technology.
Issue 1: Broken Heading Hierarchy
My page jumped from <h1> straight to <h4> because I picked headings by font size, not structure. Screen reader users navigate by headings — a skipped level breaks their mental outline.
The fix: I rewrote the hierarchy so it follows a logical order:
html
<h1>Rodricks Okoyo — Web Developer</h1>
<h2>About me</h2>
<h3>My story</h3>
<h2>Projects</h2>
<h3>Portfolio Website</h3>
<h3>Accessible Contact Form</h3>
CSS controls the size. HTML controls the meaning. Never mix the two.
Issue 2: Images Without alt Text
My project screenshots had no alt attribute, so screen readers announced them as "image" with no context.
html
<!-- Before -->
The fix:
html
<!-- After -->
alt="Screenshot of the Portfolio Website project">
Now a screen reader user hears what the image shows, not just that one exists.
Issue 3: Vague Link Text
Every project card had the same link text: "Read more." Screen reader users often browse by pulling up a list of all links on a page — three "Read more" links tell them nothing.
The fix:
html
`<!-- Before -->
Read more
View the Nimbus Analytics Dashboard project`
Longer, yes. But every link is now self-explanatory even out of context.
Issue 4: Missing lang and Page Indicators
Two smaller fixes worth mentioning:
My <html> tag had no language, so screen readers didn't know how to pronounce the content. Fixed with <html lang="en">.
My navigation gave no programmatic hint about which page was current. Fixed with aria-current="page" on the active link.
The Result
After these fixes, the portfolio is much more usable for assistive technology.
You can see the live portfolio here: [https://okoyo13.github.io/iyf-s12-week-01-okoyo13/]
Source code on GitHub: [https://github.com/okoyo13/iyf-s12-week-01-okoyo13]
If you want to run your own audit:
Lighthouse — built into Chrome DevTools (F12 → Lighthouse tab)
WAVE — wave.webaim.org, visual overlay of issues
axe DevTools — browser extension with detailed reports
Final Thoughts
Semantic HTML isn't about being "correct" for its own sake. It's about respecting the people who use your site. Most of my fixes took under an hour, cost nothing, and made my portfolio dramatically more usable for users who navigate the web differently than I do.
Write HTML like it matters. Because for someone out there, it does.
What accessibility issues have you found in your own projects? Drop them in the comments — I'd love to learn from them.
Top comments (0)