> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acondawayuno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Accessibility

> Keyboard, semantic-index, dialog, reduced-motion, and WebGL-fallback behavior for built-in and custom assets.

The accessibility model does not require a visitor to understand or operate a
3D canvas. Every **active interactive** asset must have an equivalent HTML
chapter in the content index and detail dialog.

无障碍目标不是让读屏软件解释三维模型，而是保证访客不进入 3D 也能访问每一个当前启用的
交互章节。

## Semantic parity / 语义等价

The active interactive set is:

* enabled built-in assets; plus
* custom assets whose behavior is `interactive`.

Disabled built-ins and decorative custom assets are intentionally excluded from
the interactive index and deep links. When adding a custom interactive asset,
provide localized object labels, titles, introductions, and card content so
the DOM experience is meaningful without the model.

The starter ships with 12 built-in chapters, but 12 is not a runtime invariant.
The accessible index follows the current scene configuration.

## Keyboard paths / 键盘路径

| Key                   | Action                                  |
| --------------------- | --------------------------------------- |
| `Tab` / `Shift + Tab` | Move through controls and index entries |
| `Enter` / `Space`     | Activate a focused button or chapter    |
| `Esc`                 | Close the active overlay or panel       |
| Arrow keys            | Orbit the focused room canvas           |
| `+` / `-`             | Zoom the focused room canvas            |
| `R`                   | Reset the camera                        |

The first keyboard path includes a skip link that opens the content index
without requiring canvas interaction. When a detail dialog opens, focus moves
to its close control; closing attempts to restore focus to the source element.

## Dialogs and names / 对话框与名称

Content, instant-photo, help, and modal Studio surfaces use semantic dialog
roles and accessible labels. The canvas is a focusable region with instructions,
while the index supplies ordinary HTML buttons and text for assistive
technology.

When extending the interface:

* give every icon-only control an accessible name;
* associate form labels, descriptions, validation, and live status text;
* preserve the close-and-return focus behavior;
* do not make color the only indication of loading, error, selection, or
  interactivity;
* keep decorative scene objects out of the tab order.

## Reduced motion / 减少动态效果

The room checks `prefers-reduced-motion`. Camera focus transitions jump rather
than tween when reduction is requested, and CSS disables or shortens
non-essential interface motion.

Test both settings after adding animation. A procedural decoration should
either stop, become substantially calmer, or remain purely static when motion
is not necessary to understand it.

## WebGL and JavaScript fallback / 降级体验

If WebGL initialization or the context fails, the application exposes the
lightweight semantic index for active interactive content. A `<noscript>`
baseline list also keeps starter content visible with JavaScript disabled.

Because `<noscript>` is static source, verify it whenever you substantially
change the built-in baseline. Dynamic custom scene state cannot be discovered
by JavaScript after JavaScript has been disabled.

## Manual acceptance checklist / 人工验收

* [ ] Complete the experience using only the keyboard.
* [ ] Reach every current interactive chapter through the content index.
* [ ] Confirm disabled and decorative assets do not create dead index entries.
* [ ] Verify focus placement and restoration for every modal surface.
* [ ] Test VoiceOver and at least one Windows or Android screen reader when
  those platforms are in scope.
* [ ] Test browser zoom at 200% and narrow mobile safe areas.
* [ ] Test `prefers-reduced-motion: reduce`.
* [ ] Simulate WebGL failure and confirm the content index remains usable.
* [ ] Check new colors and focus indicators against the contrast target chosen
  for the project.

Automated linting and smoke tests help, but they do not replace these manual
checks.
