Skip to content

Accessibility

Zensical provides accessibility-friendly defaults. This page summarizes the configuration and best practices used in this POC.

Configuration

Theme Features

The following Zensical theme features improve accessibility:

  • Keyboard navigation — All interactive elements are keyboard-accessible
  • Skip links — "Skip to content" for screen reader users
  • Semantic structure — Proper heading hierarchy and landmark roles
  • Color contrast — Default and slate palettes meet WCAG contrast guidelines

Color Scheme

The POC uses the default (light) and slate (dark) schemes. Both provide sufficient contrast. The theme toggle allows users to choose their preference.

Configuration in zensical.toml:

[[project.theme.palette]]
scheme = "default"
toggle.icon = "lucide/sun"
toggle.name = "Switch to dark mode"

[[project.theme.palette]]
scheme = "slate"
toggle.icon = "lucide/moon"
toggle.name = "Switch to light mode"

Best Practices

  1. Heading hierarchy — Use H1 → H2 → H3 in order; don't skip levels.
  2. Link text — Prefer descriptive link text (e.g., "Getting Started guide" instead of "click here").
  3. Images — Provide alt text for meaningful images.
  4. Tables — Use header cells (| Header |) for table headers.
  5. Code blocks — Use language tags for syntax highlighting and better context.

Linkable Headers

All headers in the documentation generate anchor links. Hover over a heading to see the link icon and copy the URL. For example:

Responsive Design

Zensical's theme is responsive and adapts to different screen sizes:

  • Desktop — Full navigation, search, and sidebar
  • Tablet — Collapsible navigation
  • Mobile — Optimized layout and touch targets

Resources