AgentSkillsCN

interface-guidelines

构建 UI 时应遵循的无障碍性与交互规则。适用于构建表单、按钮、导航、动画，或任何交互式元素时使用。

SKILL.md
--- frontmatter
name: interface-guidelines
description: Accessibility and interaction rules for building UIs. Use when building forms, buttons, navigation, animations, or any interactive elements.

Interface Guidelines

Concise rules for building accessible, fast, delightful UIs. Use MUST/SHOULD/NEVER to guide decisions.

Interactions

Keyboard

  • •MUST: Full keyboard support per WAI-ARIA APG
  • •MUST: Visible focus rings (:focus-visible)
  • •MUST: Manage focus (trap, move, return) per APG patterns
  • •NEVER: outline: none without visible focus replacement

Targets & Input

  • •MUST: Hit target ≥24px (mobile ≥44px)
  • •MUST: Mobile <input> font-size ≥16px to prevent iOS zoom
  • •NEVER: Disable browser zoom
  • •MUST: touch-action: manipulation to prevent double-tap zoom

Forms

  • •MUST: Hydration-safe inputs (no lost focus/value)
  • •NEVER: Block paste in inputs
  • •MUST: Loading buttons show spinner and keep original label
  • •MUST: Enter submits focused input; in textarea, ⌘/Ctrl+Enter submits
  • •MUST: Errors inline next to fields; on submit, focus first error
  • •MUST: autocomplete + meaningful name; correct type and inputmode
  • •MUST: Compatible with password managers & 2FA

State & Navigation

  • •MUST: URL reflects state (deep-link filters/tabs/pagination)
  • •MUST: Back/Forward restores scroll position
  • •MUST: Links use <a> for navigation (support Cmd/Ctrl/middle-click)
  • •NEVER: Use <div onClick> for navigation

Feedback

  • •SHOULD: Optimistic UI; reconcile on response
  • •MUST: Confirm destructive actions or provide Undo
  • •MUST: Use polite aria-live for toasts/inline validation

Animation

  • •MUST: Honor prefers-reduced-motion
  • •MUST: Animate compositor-friendly props (transform, opacity) only
  • •NEVER: Animate layout props (top, left, width, height)
  • •NEVER: transition: all—list properties explicitly
  • •SHOULD: Use ease-out-quart/quint/expo for natural deceleration
  • •MUST: Animations interruptible and input-driven

Layout

  • •SHOULD: Optical alignment; adjust ±1px when perception beats geometry
  • •MUST: Verify mobile, laptop, ultra-wide
  • •MUST: Respect safe areas (env(safe-area-inset-*))
  • •MUST: Avoid unwanted scrollbars

Content & Accessibility

  • •MUST: Skeletons mirror final content to avoid layout shift
  • •MUST: <title> matches current context
  • •MUST: No dead ends; always offer next step/recovery
  • •MUST: Design empty/sparse/dense/error states
  • •MUST: font-variant-numeric: tabular-nums for number comparisons
  • •MUST: Redundant status cues (not color-only)
  • •MUST: Icon-only buttons have descriptive aria-label
  • •MUST: Prefer native semantics before ARIA

Performance

  • •MUST: Track and minimize re-renders
  • •MUST: Mutations target <500ms
  • •MUST: Virtualize large lists (>50 items)
  • •MUST: Preload above-fold images; lazy-load the rest
  • •MUST: Prevent CLS (explicit image dimensions)

Dark Mode & Theming

  • •MUST: color-scheme: dark on <html> for dark themes
  • •SHOULD: <meta name="theme-color"> matches page background
  • •MUST: Native <select>: explicit background-color and color

Design

  • •SHOULD: Layered shadows (ambient + direct)
  • •SHOULD: Crisp edges via semi-transparent borders + shadows
  • •SHOULD: Nested radii: child ≤ parent; concentric
  • •SHOULD: Tint borders/shadows/text toward bg hue
  • •MUST: Meet contrast—prefer APCA over WCAG 2
  • •MUST: Increase contrast on hover/active/focus