Introduction
Accessibility isn't just about code — content itself can be inaccessible. Poorly written alt text, missing headings, complex language, and walls of unstructured text create barriers for users with cognitive disabilities, learning differences, and visual impairments.
Content accessibility means writing clear, structured text that works with assistive technology. Screen readers navigate by headings. Alt text conveys meaning. Plain language reaches more people than jargon. These are skills every developer and content creator should have.
This guide covers writing effective alt text, structuring content with headings, plain language principles, and creating readable layouts.
Key Concepts
Writing Alt Text
html
// ✅ Descriptive: convey the meaning/function
<img src="chart.png" alt="Bar chart showing revenue growth from $2M in 2023 to $3.5M in 2025" />
// ✅ Functional: describe what it does
<img src="search-icon.svg" alt="Search" />
// ✅ Decorative: empty alt
<img src="decorative-swoosh.svg" alt="" />
// ❌ Redundant: don't repeat surrounding text
// Heading says "Meet our CEO"
<img src="ceo.jpg" alt="Photo of our CEO" /> // Redundant
<img src="ceo.jpg" alt="Sarah Chen smiling at her desk" /> // Descriptive ✅
// ❌ Filename as alt
<img src="IMG_4523.jpg" alt="IMG_4523.jpg" />
Heading Structure
html
<!-- ✅ Logical hierarchy -->
<h1>Getting Started with React</h1> <!-- One per page -->
<h2>Installation</h2>
<h3>Using Create Next App</h3>
<h3>Manual Setup</h3>
<h2>Your First Component</h2>
<h3>Function Components</h3>
<h3>JSX Syntax</h3>
<h2>Next Steps</h2>
<!-- ❌ Skipping levels -->
<h1>Title</h1>
<h3>Subsection</h3> <!-- Skipped h2! -->
<h5>Detail</h5> <!-- Skipped h3 and h4! -->
<!-- ❌ Using headings for styling -->
<h4>This text should just be bold, not a heading</h4>
Plain Language Principles
- Use short sentences (under 25 words on average)
- Use common words — 'use' not 'utilize', 'help' not 'facilitate'
- Write in active voice — 'Click the button' not 'The button should be clicked'
- One idea per paragraph
- Define technical terms on first use
- Use lists for 3+ related items
Practical Examples
1. Alt Text Decision Tree
javascript
function getAltText(image) {
// 1. Is it purely decorative? → alt=""
if (image.isDecorative) return '';
// 2. Is it a functional image (button, link)? → Describe the function
if (image.isLink) return `Go to ${image.destination}`;
if (image.isButton) return image.action; // "Search", "Close", "Play video"
// 3. Is it informative? → Describe the information
// Chart: describe the data story
// Photo: describe relevant details
// Screenshot: describe what's shown
return image.meaningfulDescription;
// 4. Is it a complex image (chart, diagram)? → Short alt + long description
// alt="Revenue by quarter, details below"
// Then provide a data table or detailed description
}
2. Readable Content Layout
css
/* Readable text styling */
.content {
max-width: 65ch; /* Optimal line length */
line-height: 1.6; /* Comfortable reading */
font-size: 1rem; /* Minimum 16px */
color: #374151; /* High contrast on white */
}
.content p {
margin-bottom: 1rem; /* Space between paragraphs */
}
.content h2 {
margin-top: 2rem; /* Visual separation */
}
/* Don't justify text — uneven spacing is hard to read */
.content { text-align: left; } /* ✅ */
.content { text-align: justify; } /* ❌ */
3. Accessible Link Text
html
// ❌ Non-descriptive links
<a href="/docs">Click here</a>
<a href="/pricing">Read more</a>
<a href="/report.pdf">Learn more</a>
// ✅ Descriptive links
<a href="/docs">View the documentation</a>
<a href="/pricing">See pricing plans</a>
<a href="/report.pdf">Download the 2025 annual report (PDF, 2.3MB)</a>
// ✅ When visual design limits link text, use aria-label
<a href="/docs" aria-label="View React documentation">Docs</a>
Best Practices
- ✅ Write alt text that conveys meaning, not just appearance
- ✅ Maintain a logical heading hierarchy — never skip levels
- ✅ Keep line length under 80 characters (65ch is optimal)
- ✅ Use descriptive link text — 'Download report' not 'Click here'
- ✅ Break up long content with headings, lists, and short paragraphs
- ❌ Don't start alt text with 'Image of' or 'Photo of' — screen readers already say 'image'
- ❌ Don't use ALL CAPS for emphasis — screen readers may spell it letter by letter
Common Pitfalls
- Empty alt on informative images — they're skipped entirely by screen readers
- Using headings for visual styling instead of document structure
- Link text that makes no sense out of context ('here', 'more', 'this')
- Long unbroken paragraphs — hard for everyone, especially users with cognitive disabilities
Related Guides
- WCAG Practical Guide — Content-related success criteria
- Screen Reader Testing — Hear how your content is actually announced
- Next.js Internationalization (i18n) — Writing content for multiple languages
- Design System Documentation — Accessible documentation patterns