导航与渐进展开Navigation & progressive disclosure

# 导航与渐进展开 / Navigation & progressive disclosure

ID: navigation
Version: 1.2.1

主导航对应稳定任务目录，把搜索、收藏和站点说明安排在合适层级。

Map primary navigation to stable task sections, with search, saved items, and site information at appropriate levels.

## Anatomy
- 品牌入口与五个任务目录构成全站主导航。
  The brand entry and five task sections form the global navigation.
- 更多菜单承载搜索、更新记录、关于和设计规范。
  More contains search, update notes, about, and design guidelines.
- 独立规范目录仅在规范库出现，不占用资源分类页。
  The documentation index appears only in the handbook, not resource sections.

## Parameters
- nav.active: aria-current=page
  当前位置不是 hover，离开鼠标后仍保留标记。
  The current page is not a hover state and remains marked after pointer exit.
- menu.primitive: details / summary
  菜单在无 JavaScript 时仍可展开。
  Menus remain operable without JavaScript.
- list.initial: 24
  目录初始展示 24 条，再按需展开。
  Show 24 entries first, then reveal more on request.

## Rules
- 搜索只在独立搜索页提供完整条件，目录浏览首屏先给内容。
  Keep full search controls on the search page and show content first in sections.
- 折叠菜单支持 Escape 关闭并把焦点还给触发器。
  Escape closes the menu and returns focus to its trigger.
- 展开更多条目后，把焦点移到第一条新内容。
  After revealing more entries, focus the first newly revealed item.
- 当前位置同时用文字或下划线表达，不仅靠颜色。
  Use text or an underline in addition to color for the current location.

## States
- 当前位置 / Current page: 保留强调与 aria-current，帮助用户定位。
  Keep emphasis and aria-current to indicate location.
- 菜单打开 / Menu open: 目标全部可读，内容不超出手机视口。
  Show readable destinations within the mobile viewport.
- 加载更多 / Reveal more: 按序增加内容，不跳回页首；全部显示后隐藏按钮。
  Append in order without returning to the top; hide the control once complete.

## Do / Avoid
- Do: 进入“学习与工作流”后立即浏览条目，需要查找时再打开搜索。 / Browse Learning & workflows immediately and open search when a specific goal emerges.
- Avoid: 每个分类都重复展示搜索、排序、难度和格式控件。 / Repeat search, sort, level, and format controls on every category page.

## Code mapping
- src/components/Header.astro: 全站导航与菜单 / Global navigation and menu
- src/components/DirectoryListing.astro: 渐进展开与旧链接兼容 / Progressive reveal and legacy links

## Dependencies
buttons, layout

## Acceptance
- 主导航、菜单和规范目录都能识别当前位置。
  Global, menu, and handbook navigation indicate location where relevant.
- 手机菜单不溢出，Escape 后焦点位置正确。
  Mobile menus fit and Escape restores focus.
- 旧筛选链接仍能进入对应搜索范围。
  Legacy filtered links retain their search scope.

## Implementation example
```
<a href={withBase("learn/")} aria-current={active ? "page" : undefined}>
  <Loc zh="学习与工作流" en="Learning & workflows" />
</a>
```

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