Writing Accessible Content

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

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

Writing Accessible Content

Introduction

Key Concepts

Writing Alt Text

Heading Structure

Plain Language Principles

Practical Examples

1. Alt Text Decision Tree

2. Readable Content Layout

3. Accessible Link Text

Best Practices

Common Pitfalls

Related Guides