/* ============================================================================
   focus-ring.css — 焦点环（全局基础设施 ·
   ----------------------------------------------------------------------------
   🔴 判据：WCAG 2.4.13 Focus Appearance。
   ============================================================================
   ⭐ 依据
   ----------------------------------------------------------------------------
   · **WCAG 2.4.7 Focus Visible**（A 级）—— 键盘操作必须有可见焦点
   · **WCAG 2.4.11 Focus Not Obscured (Minimum) / 2.4.13 (Enhanced)**
     —— 焦点元素**不能被固定元素遮住**（悬浮头/吸底栏会盖住）
   · **WCAG 1.4.11 非文本对比** —— 焦点指示器需 ≥ 3:1
   · **`:focus-visible` 的语义** —— **只给键盘用户看**，
     鼠标点击不显示（这正是它比 `:focus` 好的地方）

   ⚠️ 为什么用 `outline` 而不是 `box-shadow`
   · `outline` **不占布局空间** ⇒ 聚焦时**不会引起回流**（`box-shadow` 会）
   · `outline` 会**自动跟随元素的 `border-radius`**（现代浏览器）
   · `outline` 是**系统级**的：高对比度模式下浏览器会自动加强它
   ⇒ 通行做法是 `outline`，不是自绘的 box-shadow。

   ⚠️ 禁区：**不得裸写 `outline: none`**
   那会让键盘用户**完全看不到焦点**。
   若必须去掉默认环，必须在**同一规则里**立刻给出替代样式。
   （本文件末尾有一道门禁扫这个。）
   ========================================================================== */

:root {
  /* 🔴 单一真相源：全库的焦点环只认这三个令牌 */
  --focus-ring-width:   2px;
  --focus-ring-offset:  2px;
  --focus-ring-color:   var(--accent);
  --focus-ring-inset:   rgba(255, 255, 255, .9);   /* 暗色下在深底上更清楚 */
}

/* ============================================================================
   一、默认焦点环
   ----------------------------------------------------------------------------
   ⚠️ 用 `:focus-visible` 而不是 `:focus`：
   键盘 Tab 才出现，鼠标点击不出现 —— 这正是 WCAG 想要的行为。
   ========================================================================== */
:focus-visible {
  outline: var(--focus-ring-width) solid var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}

/* ============================================================================
   二、暗色下的加强
   ----------------------------------------------------------------------------
   暗色底上纯 `outline` 可能不够清楚（对比不足）⇒ 加一层内描边。
   ⚠️ 用 `box-shadow` 而不是改 outline —— 这样**不占布局**。
   ==========================================================================
   🔴 暗色改为纯 CSS 表达（见 docs/BENCHMARK.md 一、二节）
   ----------------------------------------------------------------------------
   ⚠️ 两个选择器都要写：
     · data-theme-current = **解析后**生效的明暗（由 JS 落，覆盖"跟随系统"）
     · data-theme         = **使用者显式选的**（纯 CSS，不加载 JS 也成立）
     只写前者 ⇒ 不加载 JS 时强制暗色的页面拿不到加强；只写后者 ⇒ 跟随系统
     进入的暗色拿不到加强。两个都不能省。

   🔴 `data-theme` 两项**不写 `:root` 限定**：暗色可挂在任意容器上
     （RFC-THEME-SCOPE D1）。`data-theme-current` 仍限 `:root` —— 那是 JS 落在根上的。 */
[data-theme="dark"] :focus-visible,
[data-theme="dark"]:focus-visible,
:root[data-theme-current="dark"] :focus-visible,
:root[data-theme-current="dark"]:focus-visible {
  outline-color: var(--accent-hover);
  box-shadow: 0 0 0 1px var(--focus-ring-inset);
}

/* ============================================================================
   三、焦点不被遮住（WCAG 2.4.11）
   ----------------------------------------------------------------------------
   固定头/吸底栏可能盖住聚焦元素。
   ⇒ 给这些固定元素加 `scroll-margin`，聚焦时浏览器会自动留出空间。
   ========================================================================== */
:where(a, button, input, select, textarea, [tabindex]) {
  scroll-margin-block: var(--focus-ring-offset) 5vh;
}

/* ============================================================================
   四、只在键盘时"上浮"（可选的增强）
   ----------------------------------------------------------------------------
   聚焦时轻微提亮，帮助用户追踪焦点在长内容里的位置。
   ⚠️ 用 `transition` 且尊重 reduced-motion。
   ========================================================================== */
@media (prefers-reduced-motion: no-preference) {
  :where(a, button, [role="button"], [role="tab"]) {
    transition: outline-offset var(--dur-fast) var(--ease-out);
  }
  :where(a, button, [role="button"], [role="tab"]):focus-visible {
    outline-offset: calc(var(--focus-ring-offset) + 1px);
  }
}

/* ============================================================================
   五、工具类：给需要"内嵌焦点环"的场景（如已有一层边框的按钮）
   ----------------------------------------------------------------------------
   用 `outline-offset: -2px` 把环画在**元素内侧**，不撑大布局。
   ========================================================================== */
.focus-inset:focus-visible {
  outline-offset: calc(var(--focus-ring-width) * -1);
}