Why Semantic HTML and accessibility Matter: Lessons From my portfolio Audit

When building for the web, it is easy to focus entirely on visual aesthetics. However, clean code under the hood is what truly separates good websites from great ones. During my recent portfolio review, I took a deep dive into semantic HTML and web accessibility (a11y).

Semantic HTML refers to using markup tags that inherently describe the meaning and purpose of the content enclosed within them. Rather than relying on generic containers like div or span for everything, semantic code utilizes dedicated tags such as header, nav, main, and footer. This practice matters profoundly because it structures data so search engines can index pages effectively, boosting SEO. More importantly, it creates an essential structural map for screen readers, allowing visually impaired users to seamlessly navigate a website.

Before vs After: Writing Meaning

<!-- Before: Non-semantic markup -->
<div class="navigation-bar">
  <div class="nav-item">Home</div>
  <div class="nav-item">Projects</div>
  <div class="nav-item">Contact</div>
</div>

<!-- After: Semantic markup -->
<nav>
  <ul>
    <li>Home</li>
    <li>Projects</li>
    <li>Contact</li>
  </ul>
</nav>

Fixing My Portfolio Accessibility Issues

When conducting an accessibility audit on my personal portfolio site, I discovered three major issues that severely compromised user experience:

1. Missing image Alt text: Several project screenshots completely lacked alt attributes. This meant screen readers would simply announce the raw file name to a visually impaired user. I resolved this by adding clear, descriptive text to every image tag.

2. Heading hierarchy errors: My layout skipped directly from an h1 tag to an h3 tag. I restructured the headings to follow a logical, consecutive hierarchy (h1, h2, h3) for proper page layout reading.

3. Missing document language: The main template was missing a lang attribute entirely. I added lang="en" directly to the root html element to ensure screen readers use the correct pronunciation.

Conclusion

Prioritizing accessibility ensures that the digital world remains open and inclusive for everyone. You can view my fully optimized accessibility project live here: My deployed portfolio