{
  "id": "skip-link",
  "type": "a11y",
  "status": "published",
  "name": {
    "zh": "跳过链接",
    "en": "Skip Link"
  },
  "aliases": [
    "跳过导航",
    "跳到主内容",
    "跳过链接",
    "一键跳正文",
    "skip nav",
    "skip navigation"
  ],
  "category": [
    "Accessibility",
    "Navigation"
  ],
  "description": {
    "zh": "页面第一个可聚焦元素，通常是视觉上隐藏的链接；键盘用户按下第一个 Tab 就能看见它，激活后直接跳到主内容区，不必逐个穿过顶部导航链接。长导航站点的必备逃生口，WCAG 称之为「跳过区块」。",
    "en": "The first focusable element on the page — usually a visually hidden link. Keyboard users meet it on the first Tab, activate it, and land straight in the main content without walking every nav link. The mandatory escape hatch on nav-heavy sites; WCAG calls it \"bypass blocks\"."
  },
  "use_when": [
    {
      "zh": "顶部导航链接超过 5 个，且每页重复出现",
      "en": "Repeated page chrome with more than a handful of nav links"
    },
    {
      "zh": "单页应用路由切换后焦点需要有处可去",
      "en": "SPAs where focus needs a resting place after route changes"
    },
    {
      "zh": "页头含搜索、登录、语言切换等大量可聚焦项",
      "en": "Headers crowded with search, login and locale switchers"
    }
  ],
  "avoid_when": [
    {
      "zh": "导航只有两三个链接，跳过收益小于复杂度",
      "en": "Navs with two or three links — bypassing costs more than it saves"
    },
    {
      "zh": "把「跳过」做成页头第一个常驻菜单项而不是隐藏链接",
      "en": "Shipping it as a permanent first nav item instead of a hidden link"
    },
    {
      "zh": "跳过目标没有 tabindex=\"-1\"，锚点落点不可聚焦",
      "en": "Targets without tabindex=\"-1\" so the jump lands on an unfocusable node"
    }
  ],
  "tags": [
    "a11y",
    "navigation",
    "keyboard",
    "landmark"
  ],
  "api": [
    "<a href=\"#main\">",
    "tabindex",
    "landmark roles"
  ],
  "framework_names": [
    {
      "framework": "WCAG",
      "name": "2.4.1 Bypass Blocks",
      "url": "https://www.w3.org/WAI/WCAG21/Understanding/bypass-blocks"
    },
    {
      "framework": "WebAIM",
      "name": "Skip Navigation",
      "url": "https://webaim.org/techniques/skipnav/"
    }
  ],
  "disambiguation": {
    "zh": "跳过链接不是「返回顶部」——跳过链接在文档流最前、服务键盘用户跳过导航；返回顶部出现在长页底部，服务滚动浏览者。",
    "en": "A skip link is not \"back to top\" — the skip link sits first in the document for keyboard users escaping nav; back-to-top sits at the bottom of long pages for scrollers."
  },
  "confusable": [
    {
      "id": "navbar",
      "note": {
        "zh": "navbar 是被跳过的长导航本身，不是跳过机制；把「跳过导航」塞成 navbar 第一项就失去了意义。",
        "en": "navbar is the long nav being skipped, not the skipping mechanism — making \"skip nav\" its first item defeats the point."
      }
    }
  ],
  "variants": [
    {
      "id": "chip",
      "name": {
        "zh": "左上角芯片",
        "en": "Corner chip"
      },
      "note": {
        "zh": "聚焦时浮现在左上角，最常见",
        "en": "Appears top-left on focus — the common default"
      }
    },
    {
      "id": "bar",
      "name": {
        "zh": "全宽横条",
        "en": "Full-width bar"
      },
      "note": {
        "zh": "聚焦时横贯页头，更难错过",
        "en": "Spans the header on focus — harder to miss"
      }
    },
    {
      "id": "inline",
      "name": {
        "zh": "行内常驻",
        "en": "Persistent inline"
      },
      "note": {
        "zh": "始终可见的小字链接，代价是占一条视觉行",
        "en": "Always-visible small link — costs a line of visual space"
      }
    }
  ],
  "anatomy": [
    "跳过链接（Skip link）",
    "地标目标（Landmark targets）"
  ],
  "related": [
    {
      "id": "keyboard-navigation",
      "relation": "used_with"
    },
    {
      "id": "navbar",
      "relation": "used_with"
    },
    {
      "id": "focus-ring",
      "relation": "used_with"
    }
  ],
  "demo": {
    "component": "skip-link",
    "modes": [
      "default",
      "dark",
      "variants"
    ]
  },
  "sources": [
    {
      "name": "WCAG 2.1 Bypass Blocks",
      "url": "https://www.w3.org/WAI/WCAG21/Understanding/bypass-blocks"
    },
    {
      "name": "WebAIM — Skip Navigation",
      "url": "https://webaim.org/techniques/skipnav/"
    }
  ],
  "implementation": {
    "css": [
      "clip-path",
      ":focus",
      "position: absolute",
      "scroll-margin-top"
    ],
    "notes": {
      "zh": "隐藏用 position:absolute + clip-path:inset(50%)（或 left:-9999px），:focus 时恢复到视口内并给足对比度；目标区 main 加 tabindex=\"-1\" 并 scroll-margin-top 抵消吸顶页头。放在 <body> 最前、页头之前。SPA 可在路由切换后用它归还焦点。",
      "en": "Hide with `position:absolute` + `clip-path:inset(50%)` (or left:-9999px) and restore inside the viewport on :focus with solid contrast. Give the target main `tabindex=\"-1\"` and scroll-margin-top to clear sticky headers. Place it first in <body>, before the header. SPAs can reuse it to park focus after route changes."
    }
  },
  "prompts": {
    "basic": {
      "zh": "给站点加一个跳过链接：第一个 Tab 就能跳过顶部导航直达主内容。",
      "en": "Add a skip link so the first Tab jumps over the top nav straight to the main content."
    },
    "design": {
      "zh": "页头之前放一个默认隐藏的链接「跳到主内容」，聚焦时出现在左上角、强调色底、对比度达标；激活后焦点落到主内容区，页面不再逐个经过导航项。",
      "en": "Place a hidden \"Skip to main content\" link before the header; on focus it surfaces top-left on the accent surface with passing contrast; activating it moves focus into main and spares the user every nav item."
    },
    "implementation": {
      "zh": "<a href=\"#main\" class=\"skip-link\">跳到主内容</a> 置于 body 首位；CSS 隐藏 clip-path:inset(50%)，:focus 时 clip-path:none + position:fixed 左上角。<main id=\"main\" tabindex=\"-1\">。激活后可选 main.focus() 让读屏继续朗读。",
      "en": "First in body: `<a href=\"#main\" class=\"skip-link\">Skip to main</a>`. CSS hides it with clip-path:inset(50%), on :focus resets clip-path and pins it top-left. Target `<main id=\"main\" tabindex=\"-1\">`; optionally call main.focus() on activation so reading continues there."
    },
    "agent": {
      "zh": "在当前项目中实现跳过链接。\n先检查现有组件体系和 Design Token，优先复用当前组件。\n要求：\n- 链接位于文档流最前，视觉隐藏、聚焦可见\n- 激活后焦点与滚动位置落到主内容地标\n- 与现有页头/导航结构集成，不改变视觉稿\n保持现有项目视觉风格。不要新增不必要依赖。\n尊重 prefers-reduced-motion。\n完成后运行项目现有检查，并列出修改的文件。",
      "en": "Implement a skip link in the current project.\nInspect the existing component system and design tokens first; reuse current components.\nRequirements:\n- Link first in the document, visually hidden until focused\n- Activation moves focus and scroll position to the main landmark\n- Integrate with the existing header/nav without altering the visual design\nKeep the existing visual style. Add no unnecessary dependencies.\nRespect prefers-reduced-motion.\nRun the project's existing checks when done and list the modified files."
    }
  }
}