Communitygithub.com

adeyanjufuhad/astrolabe

Vercel Web 界面指南。构建可访问、快速、令人愉悦的 Web UI 的 MUST/SHOULD/NEVER 规则（涵盖键盘、目标、表单、动效、布局、内容、性能、主题）。适用于构建、审查或审计任何网页或组件，包括 site/ 中的 Astrolabe 着陆页。

astrolabe 是什么？

这是一个基于 Vercel 官方 Web 界面指南的 AI 技能，旨在帮助开发者构建可访问、高性能且令人愉悦的用户界面。它通过 MUST/SHOULD/NEVER 指令明确规定了从交互、动画到主题和性能的每个方面，为开发者提供了具体的实现标准。该技能涵盖了键盘支持、触摸目标大小、表单行为、状态管理、反馈机制、动画性能、布局对齐、内容可访问性、性能优化（如 CLS 预防、渲染分析）以及暗黑模式兼容性等关键领域。它适用于指导新项目的构建、代码审查以及现有界面的审计，支持 Vercel 平台上的 Astrolabe 着陆页等 Web 项目。技能的核心价值在于将最佳实践转化为可执行的操作规则，从而减少设计决策中的模糊性并提升 UI 整体质量。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/adeyanjufuhad/astrolabe/tree/HEAD/.claude/skills/web-interface-guidelines
查看原文→浏览所有技能

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

文档

构建可访问、快速、令人愉悦的 UI 的简洁规则。使用 MUST/SHOULD/NEVER 来指导决策。

交互

键盘

  • MUST: 根据 WAI-ARIA APG 提供完整的键盘支持
  • MUST: 可见且不被遮挡的焦点环（使用 :focus-visible；与 :focus-within 配合使用）；固定/粘性元素绝对不能遮盖焦点
  • MUST: 按照 APG 模式管理焦点（捕获、移动、返回）
  • NEVER: 在没有可见焦点替代的情况下使用 outline: none

点击目标与输入

  • MUST: 点击目标大小 ≥24px（移动端 ≥44px）；如果视觉尺寸 <24px，则扩展点击区域
  • MUST: 移动端 <input> 的 font-size ≥16px 以防止 iOS 缩放
  • NEVER: 禁用浏览器缩放（user-scalable=no、maximum-scale=1）
  • MUST: 使用 touch-action: manipulation 以防止双击缩放
  • SHOULD: 设置 -webkit-tap-highlight-color 以匹配设计

表单

  • MUST: 保证水合安全的输入（不丢失焦点/值）
  • NEVER: 在 <input>/<textarea> 中阻止粘贴
  • MUST: 加载按钮显示旋转器并保留原始标签
  • MUST: 回车键提交焦点所在输入；在 <textarea> 中，⌘/Ctrl+Enter 提交
  • MUST: 在请求开始前保持提交按钮可用；然后禁用并显示旋转器
  • MUST: 接受自由文本，之后验证——不要阻止输入
  • MUST: 允许提交不完整的表单以显示验证错误
  • MUST: 错误内联显示在字段旁边；提交时，聚焦第一个错误
  • MUST: 使用 autocomplete 和有意义的 name；正确的 type 和 inputmode
  • SHOULD: 对电子邮件/代码/用户名禁用拼写检查
  • SHOULD: 占位符以 … 结尾并显示示例模式
  • MUST: 在导航前警告未保存的更改
  • MUST: 与密码管理器和双因素认证兼容；允许粘贴验证码
  • MUST: 裁剪值以处理文本扩展产生的尾随空格
  • MUST: 复选框/单选按钮没有死区；标签和控件共享一个点击目标

状态与导航

  • MUST: URL 反映当前状态（深层链接过滤器/标签/分页/展开面板）
  • MUST: 前进/后退恢复滚动位置
  • MUST: 链接使用 <a>/<Link> 进行导航（支持 Cmd/Ctrl/中键点击）
  • NEVER: 使用 <div onClick> 进行导航

反馈

  • SHOULD: 乐观 UI；收到响应后还原；失败时回滚或提供撤销
  • MUST: 确认破坏性操作或提供撤销窗口
  • MUST: 使用礼貌的 aria-live 区域处理提示/内联验证
  • SHOULD: 省略号（…）用于打开后续操作的选项（如“重命名…”）和加载状态（如“加载…”）

触摸与拖拽

  • MUST: 目标宽大，有明确的可感知操作性；避免需要精细操作的交互
  • MUST: 首次工具提示延迟显示；后续相同工具提示即时显示
  • MUST: 在模态框/抽屉中使用 overscroll-behavior: contain
  • SHOULD: 当抑制页面弹性回弹时，在 @media (pointer: fine) 内的 <html> 上设置 overscroll-behavior: none；保持粗指针设备的页面默认值以支持下拉刷新。测试混合触摸设备：pointer 描述主输入设备，none 也会禁用滚动链和原生滑动手势导航
  • MUST: 拖拽期间禁用文本选择，并对拖拽元素设置 inert
  • MUST: 拖拽/滑动/捏合/路径手势必须提供点击和键盘替代方案（除非是必要的）
  • MUST: 如果某个元素看起来可点击，则必须可点击

自动聚焦

  • SHOULD: 在桌面上自动聚焦到单一主要输入；移动端很少使用

动画

  • MUST: 尊重 prefers-reduced-motion（提供减少动画的版本或禁用动画）
  • SHOULD: 优先使用 CSS > Web Animations API > JS 库
  • MUST: 只动画化合成友好的属性（transform、opacity）
  • NEVER: 动画化布局属性（top、left、width、height）
  • NEVER: 使用 transition: all——显式列出属性
  • SHOULD: 仅在需要阐明因果或添加刻意趣味时才使用动画
  • SHOULD: 选择与变化相匹配的缓动函数（尺寸/距离/触发方式）
  • MUST: 动画可中断且由输入驱动；自动播放仅限于静音且非必要的循环
  • MUST: 与其他内容一同显示且自动播放超过 5 秒的动效，必须提供暂停、停止或隐藏控件
  • MUST: 正确的 transform-origin（动画从其“物理上”应开始的位置开始）
  • MUST: SVG 变换应用于包裹了 transform-box: fill-box 的 <g> 元素

布局

  • SHOULD: 光学对齐；当感知比几何更重要时，调整 ±1px
  • MUST: 有意对齐网格/基线/边缘——避免偶然放置
  • SHOULD: 平衡图标/文字的组合（粗细/尺寸/间距/颜色）
  • MUST: 在移动端、笔记本和超宽屏（以 50% 缩放模拟超宽屏）上进行验证
  • MUST: 尊重安全区域（env(safe-area-inset-*)）
  • MUST: 避免不需要的滚动条；修复溢出
  • SHOULD: 优先使用 Flex/Grid 而非 JavaScript 测量来实现布局

内容与可访问性

  • SHOULD: 首选内联帮助；工具提示是最后手段
  • MUST: 骨架屏应镜像最终内容以避免布局偏移
  • MUST: <title> 与当前上下文匹配
  • MUST: 没有死胡同；始终提供下一步或恢复途径
  • MUST: 设计空状态/稀疏状态/密集状态/错误状态
  • SHOULD: 使用弯引号（“ ”）；避免孤行（text-wrap: balance）
  • MUST: 对于数字比较，使用 font-variant-numeric: tabular-nums
  • MUST: 使用冗余的状态提示（不仅仅是颜色）；图标附有文本标签
  • MUST: 即使视觉上省略了标签，也必须存在可访问的名称
  • MUST: 使用 … 字符（而非 ...）
  • MUST: 标题上设置 scroll-margin-top；“跳转到内容”链接；层级化的 <h1>–<h6>
  • MUST: 能够处理用户生成的内容（短/中等/非常长）
  • MUST: 区域感知的日期/时间/数字（使用 Intl.DateTimeFormat、Intl.NumberFormat）
  • SHOULD: 对品牌名称、代码令牌和标识符使用 translate="no"，以防止自动翻译导致的乱码
  • MUST: 准确的 aria-label；装饰性元素使用 aria-hidden
  • MUST: 纯图标按钮具有描述性的 aria-label
  • MUST: 在 ARIA 之前优先使用原生语义（button、a、label、table）
  • MUST: 媒体元素根据需要提供字幕/转录/描述；控件可使用键盘操作；装饰性媒体对辅助技术隐藏
  • MUST: 使用不间断空格：10&nbsp;MB、⌘&nbsp;K、品牌名称

内容处理

  • MUST: 文本容器处理长内容（truncate、line-clamp-*、break-words）
  • MUST: Flex 子元素需要 min-w-0 以支持截断
  • MUST: 处理空状态——不因空字符串/数组而导致 UI 损坏

性能

  • SHOULD: 在 iOS 低功耗模式和 macOS Safari 中进行测试
  • MUST: 可靠地测量（禁用会干扰运行时性能的扩展）
  • MUST: 跟踪并最小化重新渲染（React DevTools/React Scan）
  • MUST: 使用 CPU/网络节流进行性能分析
  • MUST: 批量处理布局读取/写入；避免回流/重绘
  • MUST: 变更操作（POST/PATCH/DELETE）的目标响应时间 <500ms
  • SHOULD: 优先使用非受控输入；受控输入确保每次按键开销低
  • MUST: 虚拟化大型列表（超过 50 项）
  • MUST: 预加载首屏之上的图片；延迟加载其余图片
  • MUST: 防止 CLS（显式指定图片尺寸）
  • SHOULD: 为 CDN 域名使用 <link rel="preconnect">
  • SHOULD: 关键字体：使用 <link rel="preload" as="font"> 并设置 font-display: swap
  • SHOULD: 使用 <video autoplay muted loop playsinline> 替代动画 GIF；提供静态或减少动效的替代方案
  • SHOULD: 非必要的短循环应包含 Safari H.264 MP4 的 <picture> 源、prefers-reduced-motion 媒体条件以及静态回退

暗黑模式与主题

  • MUST: 在 <html> 上设置 color-scheme: dark 以启用暗黑主题
  • SHOULD: <meta name="theme-color"> 与页面背景匹配
  • MUST: 原生 <select>：显式设置 background-color 和 color（Windows 下的修复）

水合

  • MUST: 带有 value 的输入需要 onChange（或使用 defaultValue）
  • SHOULD: 保护日期/时间渲染免受水合不匹配的影响

设计

  • SHOULD: 使用分层阴影（环境光 + 直接光）
  • SHOULD: 通过半透明边框和阴影实现清晰边缘
  • SHOULD: 嵌套圆角：子元素 ≤ 父元素；同心
  • SHOULD: 色调一致性：将边框/阴影/文本的色调向背景色靠拢
  • MUST: 可访问的图表（色盲友好的调色板）
  • MUST: 满足对比度要求——优先使用 APCA 而非 WCAG 2
  • MUST: 在 :hover/:active/:focus 状态下增加对比度
  • SHOULD: 浏览器 UI 与背景匹配
  • SHOULD: 避免深色渐变条带（必要时使用背景图片）

相关技能

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community