# 加载、空白与错误反馈 / Loading, empty & error feedback

ID: feedback
Version: 1.2.1

让用户理解发生了什么、哪些内容仍可用，以及下一步能做什么。

Explain what happened, what remains usable, and what the user can do next.

## Anatomy
- 状态标题说明当前情况。
  A state heading explains the current situation.
- 短说明给出原因或限制，只写已知事实。
  A short explanation gives a known cause or constraint.
- 恢复动作具体可执行，例如重试或查看全部。
  A concrete recovery action offers retry or a broader view.

## Parameters
- loading: aria-busy=true
  仅标记正在更新的区域，不封锁无关内容。
  Mark the updating region without blocking unrelated content.
- status: role=status / polite
  复制完成、收藏变更等非阻断结果。
  Non-blocking results such as copied text or saved state.
- feedback.duration: 4.5s
  短暂操作提示可自动消失；错误原因留在原区域。
  Transient confirmations may clear automatically; persistent errors remain in context.

## Rules
- 加载骨架预留内容尺寸，不能把“没有内容”当成“仍在加载”。
  Reserve content dimensions with skeletons and distinguish no content from still loading.
- 局部失败只影响对应模块，保留导航、已有内容和退出方式。
  Contain failures to the affected module while retaining navigation and usable content.
- 空状态给出可操作的下一步，避免只留一个空白盒。
  Empty states offer a next step instead of an unexplained blank box.
- 错误状态不能只有红色；写清可确认的原因和重试方式。
  Errors require words as well as red, with a known reason and a retry path.

## States
- 加载中 / Loading: 展示稳定占位；完成后替换为内容并结束 busy 状态。
  Show a stable placeholder, then replace it with content and clear busy state.
- 无匹配 / No matches: 说明当前没有匹配项，提供清除条件或浏览入口。
  Explain the lack of matches and offer reset or browsing.
- 失败 / Failure: 保留上下文，重试只作用于失败模块。
  Keep context and retry the affected module only.
- 完成 / Complete: 即时反馈并保留可继续操作的状态。
  Announce completion while keeping the interface usable.

## Do / Avoid
- Do: “未能复制，可选中文字或下载文件”，仍保留文档。 / Copy failed; select the text or download the file, while keeping the document accessible.
- Avoid: 仅弹出“错误”，或因一张预览失败让整页不可点击。 / Show only Error, or block the whole page because one preview failed.

## Code mapping
- src/components/DirectoryExplorer.astro: 真实搜索空状态 / Real search empty state
- src/components/BrandSpecDemo.astro: 状态转换与恢复演示 / State transitions and recovery examples

## Dependencies
buttons, assets-motion

## Acceptance
- 加载、无匹配和失败状态可以分别触发与恢复。
  Loading, no-match, and failure states can each be triggered and recovered.
- 反馈通过可读文本表达，读屏能收到结果。
  Readable text and live status expose the result.
- 恢复后焦点仍在有意义的位置。
  Recovery leaves focus in a meaningful place.

## Implementation example
```
<section aria-busy="true" aria-label="资源列表">
  <!-- Keep the layout stable while loading. -->
</section>
<p role="status" aria-live="polite"></p>
```

## Reference
Method reference: https://tmall-design.com/#case/feed
Rules, parameters, examples, and branding in this file are specific to AI UP LAB.