Astro Starlight Accessibility Checklist Tutorial

What You Are Learning

This tutorial explains accessibility basics for Starlight sites. Accessibility means making pages usable for people with different devices, abilities, browsers, input methods, and reading needs.

Headings and page structure.
Alt text for images.
Readable links.
Tables and code blocks.
Color contrast and dark mode.
Keyboard navigation basics.

The Big Picture

Clear structure
  + readable text
  + useful alt text
  + keyboard-friendly links
  + good contrast
  = more usable documentation

Heading Order

Good:
# Page Title
## Major Section
### Subsection
## Another Major Section

Avoid:
# Page Title
#### Random Small Heading
## Major Section

Alt Text for Images

Good:
![Vercel settings screen showing build command npm run build and output directory dist](/images/vercel-settings.png)

Weak:
![screenshot](/images/vercel-settings.png)

For diagrams, summarize what the diagram shows.

Link Text

Weak	Better
Click here	Read the deployment workflow tutorial
More	View the Markdown and MDX guide
Download	Download the character sheet template

Color and Contrast

Check:
- Body text contrast
- Code block contrast
- Link visibility
- Card backgrounds
- Table borders
- Warning and note boxes

Do not rely on color alone. Make sure text is readable in light and dark mode.

Code Blocks and Tables

Code blocks should be explained before and after when they are part of a lesson. Tables should be used for real tabular data, not for layout.

Good table uses:
- Command reference
- Feature comparison
- Checklist
- Metadata summary

Keyboard Navigation

Check:
- Can you tab through links?
- Is the focus visible?
- Are buttons actual buttons?
- Are links actual links?

Custom Components

Use:
<button> for actions
<a> for links
<section> for page sections
<article> for standalone cards
<nav> for navigation

Diagrams and Downloads

Diagrams should not be the only place where important information appears. Add a written summary below each diagram. When linking a download, tell the reader what kind of file it is.

[Download the printable character sheet PDF](/downloads/character-sheet.pdf)

Accessibility Checklist

[ ] Page has one clear title
[ ] Headings follow a logical order
[ ] Images have meaningful alt text
[ ] Links are descriptive
[ ] Tables have clear headers
[ ] Code blocks are explained
[ ] Text is readable in light and dark mode
[ ] Custom components use semantic HTML
[ ] Diagrams have written summaries
[ ] Important information is not color-only

Simple Rule of Thumb

Structure helps everyone.
Clear headings help everyone.
Readable links help everyone.
Good contrast helps everyone.
Text summaries help everyone.
Accessibility is good teaching.