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

[jkim323]

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.