microsoft / microsoft/hve-core

Accessibility issue: ASCII directory trees do not expose hierarchy to screen readers

Open
#2,675 0 comments 1 reaction 2 assignees Claimed by @jkim323 View on GitHub
accessibility bug documentation needs-triage
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

## Summary

ASCII directory trees on two documentation pages expose their filenames as flat code text in NVDA. The parent-child relationships conveyed visually through indentation and box-drawing characters are not available at NVDA's default punctuation setting.

This was discovered during the manual assistive-technology pass for #2566, but neither affected page is part of that pull request's `origin/main...HEAD` diff.

## Steps to reproduce

1. Build and serve the Docusaurus documentation site.
2. Start NVDA and enable browse mode.
3. Open `/hve-core/docs/customization/skills` and navigate to **Directory Structure**.
4. Read the preformatted directory tree.
5. Repeat on `/hve-core/docs/customization/prompts` under **Prompt Basics**.

## Observed behavior

NVDA reads the folder and file names but does not communicate nesting levels or parent-child relationships. For example, the spoken output does not establish that `scripts/` is a child of `api-review/` or that `validate-openapi.sh` is a child of `scripts/`.

Edge exposes each block with a `code` role and its complete text. NVDA not literally announcing “diagram” or “code block” is not the finding; the missing directory relationships are.

## Expected behavior

A screen-reader user can determine the same folder and file relationships conveyed visually, at default punctuation settings.

## Environment

- Windows 11
- Microsoft Edge 151.0.4129.72
- NVDA 2026.1.1
- NVDA browse mode
- Local Docusaurus production build

## Affected content

- `docs/customization/skills.md`
- `docs/customization/prompts.md`

## Proposed remediation

Preserve the visual tree if useful, but provide an equivalent semantic nested list or explicit hierarchy description. Avoid duplicate spoken output when both representations are present.

Add regression coverage that identifies tree-style preformatted blocks without a nearby semantic equivalent.

## Acceptance criteria

- [ ] Parent-child relationships are available to NVDA at default punctuation settings.
- [ ] The semantic representation identifies each folder and file at the correct nesting level.
- [ ] A retained visual tree does not create confusing duplicate announcements.
- [ ] Automated coverage detects tree-style preformatted blocks without an equivalent semantic representation.
- [ ] A manual NVDA pass confirms the relationships are understandable.
- [ ] A qualified accessibility reviewer confirms the result before closure.

## Accessibility assessment

- Manual result: `verified fail`
- Candidate criterion: WCAG 2.2 SC 1.3.1, Information and Relationships

The criterion mapping remains subject to qualified accessibility review.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.