modern-web-guidance

现代 Web 指南

用于搜索特定 Web 开发用例并获取相应最佳实践指南的技能。

适用场景

必须在以下情况下使用此技能：

• 在开始实现任何 Web UI、CSS 布局／动画或客户端 JS 逻辑（日期／时区、清理、性能、无障碍性）时使用，包括修复 UX 问题（例如交互卡顿、布局偏移）。
• 在创建或更新组件之前，检查是否已有标准化的现代 Web 模式。
• 避免实现临时解决方案或不必要地加载大型依赖项。

使用说明

第 1 步：搜索用例

使用 npx 直接运行 modern-web-guidance，并针对单一 Web 平台功能或 UI 模式，使用一个 2–5 个词、以动作为导向的查询：

• 让查询聚焦且通用：描述用户可见的功能（<动词> + <UI／平台对象>，如果已知，可附上目标 HTML／CSS／JS 特性名称）。省略框架／库名称（React、Vue、Tailwind 等）以及应用／领域名词（产品、路由或组件／文件名）。多功能任务应拆分为多个 search 调用。
• 示例：搜索 "light dismiss dialog" 或 "responsive data table"，而不是 "dialog"（过于简略）、"responsive table dark mode"（包含多个功能，应拆分成两次搜索），或 "close React settings modal on outside click"（包含框架／应用无关信息）。

npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_10_16-6654652b

输出示例：

[
  {
    "id": "optimize-image-priority",
    "description": "Optimize the loading priority of Largest Contentful Paint (LCP) candidate images.",
    "category": "performance",
    "featuresUsed": [ "Fetch priority" ],
    "tokenCount": 985,
    "similarity": 0.7289
  },
  {
    "id": "defer-rendering-heavy-content",
    "description": "Reduce rendering times in content-heavy web pages by deferring rendering for offscreen content.",
    "category": "performance",
    "featuresUsed": [ "content-visibility", "hidden=\"until-found\"" ],
    "tokenCount": 1250,
    "similarity": 0.6961
  }
]

注意：根据结果的 description 字段判断（而不是原始的 similarity 分数）：

• 找到匹配项：直接调用 retrieve，不要同时运行 list。
• Web UI／CSS／DOM 行为（或广泛的 UI 审查）没有匹配项：如果 search 返回 []，或因查询措辞与目录不同（或任务涉及多个类别）而返回无关描述，请运行一次 npx -y modern-web-guidance@latest list，检查该模式是否以更通用的术语收录。
• 未涵盖的主题：如果没有指南的 description 与任务直接匹配，请继续实现，不要反复重试或检索无关指南。

---

第 2 步：获取最佳实践

从搜索结果中找到相关的 id 后，调用 retrieve 获取完整指南，包括与你的任务匹配的特定用例指南，以及适用的更广泛领域指南（例如 html、css、forms、accessibility、color、performance、security）。可以传入多个以逗号分隔的 ID。

npx -y modern-web-guidance@latest retrieve "<id>"

如果输出被截断，必须重复该命令，但将结果重定向到文件并读取该文件。

输出示例： 描述实现步骤的指南 Markdown 内容……

---

第 3 步：验证是否符合指南

生成或修改代码时，在结束前对照获取的指南检查实现：

• 适用指南与回退方案：确保正确应用指南中的相关现代模式和必要的回退策略，不要强行添加用户未要求的功能。
• 完成任务：确认实现完全满足用户的要求。

第 4 步：说明技能的使用情况

在任务中参考了 modern-web-guidance 后，请在交付这些更改的回复末尾添加 ### Modern Web Guidance 部分：

• 检索到的指南影响了你的代码时：针对每个新应用的 <id> 写 一条要点（1–2 句，≤75 个词），使用第一人称说明该 <id> 要求采用的非显而易见的实现选择、CSS/API 覆盖或回退方案，以及它避免的问题，并引用该具体规则或注意事项中的简短原文（不要引用指南的概述）： - **\`**：<应用的非显而易见的 API、覆盖或回退方案，以及避免的问题>（“<具体规则或注意事项的简短原文>”）。`
  • 绝不要在上下文压缩后凭记忆猜测 <id> 或引文（如有需要，请重新运行 search/retrieve），并且只说明本轮中有指南依据的更改。
• 本轮搜索或列出了指南，但未应用任何指南时：用一句第一人称的话说明你在 modern-web-guidance 中查看了哪些主题或指南，以及为何没有应用（如果应用了任何指南，则省略）。

使用 npx / pnpx

• 如果可以使用 pnpm，优先使用 pnpx 而非 npx（注意：pnpx 不使用 -y 标志）。
• 请求工具权限时，具体将 npx -y modern-web-guidance@latest *（或 pnpx modern-web-guidance@latest *）加入允许列表，绝不要将裸命令 npx * 或 pnpx * 加入允许列表。
• 重要：在 Windows 上使用 npx 可能会失败。请改用 npx.cmd ...。
• 获取并运行 modern-web-guidance 需要出站网络访问。在沙盒、权限受限或需要审批的环境（例如 Codex、Claude Code）中，首次执行前请主动请求批准或将带网络访问权限的命令加入允许列表，以免发生沙盒网络超时。
• 在 ~/.npm 只读或受限的沙盒环境中，请设置 NPM_CONFIG_CACHE=/tmp/npm-cache。
• 如果命令因离线而挂起，请尝试以离线模式重新运行：npx --offline …。
• --skill-version 标志用于判断此 SKILL.md 是否已过时。如果已过时，系统会向 stderr 输出警告消息。

指南

• 务必先搜索，以找到最相关的指南。
• 这些指南使用原生 HTML/CSS/JS；请适配到你的框架中，同时保留现代特性：
  • 类型：对新推出的 HTML 属性进行展开或类型转换（{...({ popover: 'hint', interestfor: id, commandfor: id, switch: '' } as any)}、[attr.*]），不要移除这些属性，也不要合并 @types/react。
  • SSR 与打包工具：在 SSR 中对 window/HTMLElement 进行保护，并在客户端 effect 中通过裸 import('<pkg>') 加载 polyfill（或设置 Vite 的 build.target: 'esnext' 以支持顶层 await）——绝不要从 node_modules 复制文件。
  • DOM、ID 与 CSS：对非 VDOM 管理的节点，通过 refs 调用 showModal()/moveBefore()；生成每个实例专属的 ID/anchor-name（useId()）；并确保 :root 和 @starting-style 位于顶层／非作用域内。

解读浏览器支持与回退方案

• 默认行为：所有指南都假设 Baseline 广泛可用的功能可以安全使用，无需回退方案。对于尚未达到 Baseline 广泛可用的功能，除非用户已指定自定义浏览器支持策略，否则必须遵循指南中的回退建议。

• 自定义策略：如果用户已明确规定浏览器支持要求，请使用指南中的浏览器兼容性数据来判断是否可以安全地忽略回退方案。

  • 对于 Baseline YYYY 目标，如果某项功能的「Baseline 起始日期」<= YYYY，则该功能符合此目标。
  • 策略示例：
    • 「不要实现功能回退。」（适用于探索前沿 Web 技术的原型）
    • 「Safari 17.4+」（适用于面向 macOS 或基于 Tauri 的桌面应用的内部工具）
    • 「切勿推荐或实现 polyfill；如果核心功能需要 Baseline 新近可用的功能，请提供轻量级的自定义回退方案，或重新设计实现方式。」（以减小打包体积并避免技术债务）
    • 「假设运行环境较新，可以原生使用 Baseline 新近可用的功能，但必须严格进行功能检测，并优雅降级。」（适用于渐进增强策略）

• 主动发现策略：留意环境线索，建议在 CLAUDE.md 或 AGENTS.md 中记录策略。如果开发者：

  • 提到要针对受限运行环境构建（例如 Electron 或 Tauri）。
  • 明确排除特定目标平台（例如「我们不支持 Desktop Chrome」）。
  • 表示担心 polyfill 的复杂性、打包体积或性能开销。
  • 询问某项功能是否可以安全使用而无需回退方案。

  策略格式不限。示例如下：**Browser Support:** Allow Newly Available features, but only adopt custom fallback code that adds <= 20 lines and does not require external dependencies.