cli/assets/templates/base/quick-reference.md
当任务涉及 UI 结构、视觉设计决策、交互模式或用户体验质量控制 时，应使用此 Skill。
在以下情况必须调用此 Skill：
在以下情况建议使用此 Skill：
在以下情况无需使用此 Skill：
判断准则：如果任务会改变某个功能 看起来如何、使用起来如何、如何运动或如何被交互，就应该使用此 Skill。
供人工/AI 查阅：按 1→10 决定先关注哪类规则；需要细则时用 --domain <Domain> 查询。脚本不读取本表。
| Priority | Category | Impact | Domain | Key Checks (Must Have) | Anti-Patterns (Avoid) |
|---|---|---|---|---|---|
| 1 | Accessibility | CRITICAL | ux | Contrast 4.5:1, Alt text, Keyboard nav, Aria-labels | Removing focus rings, Icon-only buttons without labels |
| 2 | Touch & Interaction | CRITICAL | ux | Min size 44×44px, 8px+ spacing, Loading feedback | Reliance on hover only, Instant state changes (0ms) |
| 3 | Performance | HIGH | ux | WebP/AVIF, Lazy loading, Reserve space (CLS < 0.1) | Layout thrashing, Cumulative Layout Shift |
| 4 | Style Selection | HIGH | style, product | Match product type, Consistency, SVG icons (no emoji) | Mixing flat & skeuomorphic randomly, Emoji as icons |
| 5 | Layout & Responsive | HIGH | ux | Mobile-first breakpoints, Viewport meta, No horizontal scroll | Horizontal scroll, Fixed px container widths, Disable zoom |
| 6 | Typography & Color | MEDIUM | typography, color | Base 16px, Line-height 1.5, Semantic color tokens | Text < 12px body, Gray-on-gray, Raw hex in components |
| 7 | Animation | MEDIUM | ux | Duration 150–300ms, Motion conveys meaning, Spatial continuity | Decorative-only animation, Animating width/height, No reduced-motion |
| 8 | Forms & Feedback | MEDIUM | ux | Visible labels, Error near field, Helper text, Progressive disclosure | Placeholder-only label, Errors only at top, Overwhelm upfront |
| 9 | Navigation Patterns | HIGH | ux | Predictable back, Bottom nav ≤5, Deep linking | Overloaded nav, Broken back behavior, No deep links |
| 10 | Charts & Data | LOW | chart | Legends, Tooltips, Accessible colors | Relying on color alone to convey meaning |
color-contrast - Minimum 4.5:1 ratio for normal text (large text 3:1); Material Designfocus-states - Visible focus rings on interactive elements (2–4px; Apple HIG, MD)alt-text - Descriptive alt text for meaningful imagesaria-labels - aria-label for icon-only buttons; accessibilityLabel in native (Apple HIG)keyboard-nav - Tab order matches visual order; full keyboard support (Apple HIG)form-labels - Use label with for attributeskip-links - Skip to main content for keyboard usersheading-hierarchy - Sequential h1→h6, no level skipcolor-not-only - Don't convey info by color alone (add icon/text)dynamic-type - Support system text scaling; avoid truncation as text grows (Apple Dynamic Type, MD)reduced-motion - Respect prefers-reduced-motion; reduce/disable animations when requested (Apple Reduced Motion API, MD)voiceover-sr - Meaningful accessibilityLabel/accessibilityHint; logical reading order for VoiceOver/screen readers (Apple HIG, MD)escape-routes - Provide cancel/back in modals and multi-step flows (Apple HIG)keyboard-shortcuts - Preserve system and a11y shortcuts; offer keyboard alternatives for drag-and-drop (Apple HIG)touch-target-size - Min 44×44pt (Apple) / 48×48dp (Material); extend hit area beyond visual bounds if neededtouch-spacing - Minimum 8px/8dp gap between touch targets (Apple HIG, MD)hover-vs-tap - Use click/tap for primary interactions; don't rely on hover aloneloading-buttons - Disable button during async operations; show spinner or progresserror-feedback - Clear error messages near problemcursor-pointer - Add cursor-pointer to clickable elements (Web)gesture-conflicts - Avoid horizontal swipe on main content; prefer vertical scrolltap-delay - Use touch-action: manipulation to reduce 300ms delay (Web)standard-gestures - Use platform standard gestures consistently; don't redefine (e.g. swipe-back, pinch-zoom) (Apple HIG)system-gestures - Don't block system gestures (Control Center, back swipe, etc.) (Apple HIG)press-feedback - Visual feedback on press (ripple/highlight; MD state layers)haptic-feedback - Use haptic for confirmations and important actions; avoid overuse (Apple HIG)gesture-alternative - Don't rely on gesture-only interactions; always provide visible controls for critical actionssafe-area-awareness - Keep primary touch targets away from notch, Dynamic Island, gesture bar and screen edgesno-precision-required - Avoid requiring pixel-perfect taps on small icons or thin edgesswipe-clarity - Swipe actions must show clear affordance or hint (chevron, label, tutorial)drag-threshold - Use a movement threshold before starting drag to avoid accidental dragsimage-optimization - Use WebP/AVIF, responsive images (srcset/sizes), lazy load non-critical assetsimage-dimension - Declare width/height or use aspect-ratio to prevent layout shift (Core Web Vitals: CLS)font-loading - Use font-display: swap/optional to avoid invisible text (FOIT); reserve space to reduce layout shift (MD)font-preload - Preload only critical fonts; avoid overusing preload on every variantcritical-css - Prioritize above-the-fold CSS (inline critical CSS or early-loaded stylesheet)lazy-loading - Lazy load non-hero components via dynamic import / route-level splittingbundle-splitting - Split code by route/feature (React Suspense / Next.js dynamic) to reduce initial load and TTIthird-party-scripts - Load third-party scripts async/defer; audit and remove unnecessary ones (MD)reduce-reflows - Avoid frequent layout reads/writes; batch DOM reads then writescontent-jumping - Reserve space for async content to avoid layout jumps (Core Web Vitals: CLS)lazy-load-below-fold - Use loading="lazy" for below-the-fold images and heavy mediavirtualize-lists - Virtualize lists with 50+ items to improve memory efficiency and scroll performancemain-thread-budget - Keep per-frame work under ~16ms for 60fps; move heavy tasks off main thread (HIG, MD)progressive-loading - Use skeleton screens / shimmer instead of long blocking spinners for >1s operations (Apple HIG)input-latency - Keep input latency under ~100ms for taps/scrolls (Material responsiveness standard)tap-feedback-speed - Provide visual feedback within 100ms of tap (Apple HIG)debounce-throttle - Use debounce/throttle for high-frequency events (scroll, resize, input)offline-support - Provide offline state messaging and basic fallback (PWA / mobile)network-fallback - Offer degraded modes for slow networks (lower-res images, fewer animations)style-match - Match style to product type (use --design-system for recommendations)consistency - Use same style across all pagesno-emoji-icons - Use SVG icons (Heroicons, Lucide), not emojiscolor-palette-from-product - Choose palette from product/industry (search --domain color)effects-match-style - Shadows, blur, radius aligned with chosen style (glass / flat / clay etc.)platform-adaptive - Respect platform idioms (iOS HIG vs Material): navigation, controls, typography, motionstate-clarity - Make hover/pressed/disabled states visually distinct while staying on-style (Material state layers)elevation-consistent - Use a consistent elevation/shadow scale for cards, sheets, modals; avoid random shadow valuesdark-mode-pairing - Design light/dark variants together to keep brand, contrast, and style consistenticon-style-consistent - Use one icon set/visual language (stroke width, corner radius) across the productsystem-controls - Prefer native/system controls over fully custom ones; only customize when branding requires it (Apple HIG)blur-purpose - Use blur to indicate background dismissal (modals, sheets), not as decoration (Apple HIG)primary-action - Each screen should have only one primary CTA; secondary actions visually subordinate (Apple HIG)viewport-meta - width=device-width initial-scale=1 (never disable zoom)mobile-first - Design mobile-first, then scale up to tablet and desktopbreakpoint-consistency - Use systematic breakpoints (e.g. 375 / 768 / 1024 / 1440)readable-font-size - Minimum 16px body text on mobile (avoids iOS auto-zoom)line-length-control - Mobile 35–60 chars per line; desktop 60–75 charshorizontal-scroll - No horizontal scroll on mobile; ensure content fits viewport widthspacing-scale - Use 4pt/8dp incremental spacing system (Material Design)touch-density - Keep component spacing comfortable for touch: not cramped, not causing mis-tapscontainer-width - Consistent max-width on desktop (max-w-6xl / 7xl)z-index-management - Define layered z-index scale (e.g. 0 / 10 / 20 / 40 / 100 / 1000)fixed-element-offset - Fixed navbar/bottom bar must reserve safe padding for underlying contentscroll-behavior - Avoid nested scroll regions that interfere with the main scroll experienceviewport-units - Prefer min-h-dvh over 100vh on mobileorientation-support - Keep layout readable and operable in landscape modecontent-priority - Show core content first on mobile; fold or hide secondary contentvisual-hierarchy - Establish hierarchy via size, spacing, contrast — not color aloneline-height - Use 1.5-1.75 for body textline-length - Limit to 65-75 characters per linefont-pairing - Match heading/body font personalitiesfont-scale - Consistent type scale (e.g. 12 14 16 18 24 32)contrast-readability - Darker text on light backgrounds (e.g. slate-900 on white)text-styles-system - Use platform type system: iOS 11 Dynamic Type styles / Material 5 type roles (display, headline, title, body, label) (HIG, MD)weight-hierarchy - Use font-weight to reinforce hierarchy: Bold headings (600–700), Regular body (400), Medium labels (500) (MD)color-semantic - Define semantic color tokens (primary, secondary, error, surface, on-surface) not raw hex in components (Material color system)color-dark-mode - Dark mode uses desaturated / lighter tonal variants, not inverted colors; test contrast separately (HIG, MD)color-accessible-pairs - Foreground/background pairs must meet 4.5:1 (AA) or 7:1 (AAA); use tools to verify (WCAG, MD)color-not-decorative-only - Functional color (error red, success green) must include icon/text; avoid color-only meaning (HIG, MD)truncation-strategy - Prefer wrapping over truncation; when truncating use ellipsis and provide full text via tooltip/expand (Apple HIG)letter-spacing - Respect default letter-spacing per platform; avoid tight tracking on body text (HIG, MD)number-tabular - Use tabular/monospaced figures for data columns, prices, and timers to prevent layout shiftwhitespace-balance - Use whitespace intentionally to group related items and separate sections; avoid visual clutter (Apple HIG)duration-timing - Use 150–300ms for micro-interactions; complex transitions ≤400ms; avoid >500ms (MD)transform-performance - Use transform/opacity only; avoid animating width/height/top/leftloading-states - Show skeleton or progress indicator when loading exceeds 300msexcessive-motion - Animate 1-2 key elements per view maxeasing - Use ease-out for entering, ease-in for exiting; avoid linear for UI transitionsmotion-meaning - Every animation must express a cause-effect relationship, not just be decorative (Apple HIG)state-transition - State changes (hover / active / expanded / collapsed / modal) should animate smoothly, not snapcontinuity - Page/screen transitions should maintain spatial continuity (shared element, directional slide) (Apple HIG)parallax-subtle - Use parallax sparingly; must respect reduced-motion and not cause disorientation (Apple HIG)spring-physics - Prefer spring/physics-based curves over linear or cubic-bezier for natural feel (Apple HIG fluid animations)exit-faster-than-enter - Exit animations shorter than enter (~60–70% of enter duration) to feel responsive (MD motion)stagger-sequence - Stagger list/grid item entrance by 30–50ms per item; avoid all-at-once or too-slow reveals (MD)shared-element-transition - Use shared element / hero transitions for visual continuity between screens (MD, HIG)interruptible - Animations must be interruptible; user tap/gesture cancels in-progress animation immediately (Apple HIG)no-blocking-animation - Never block user input during an animation; UI must stay interactive (Apple HIG)fade-crossfade - Use crossfade for content replacement within the same container (MD)scale-feedback - Subtle scale (0.95–1.05) on press for tappable cards/buttons; restore on release (HIG, MD)gesture-feedback - Drag, swipe, and pinch must provide real-time visual response tracking the finger (MD Motion)hierarchy-motion - Use translate/scale direction to express hierarchy: enter from below = deeper, exit upward = back (MD)motion-consistency - Unify duration/easing tokens globally; all animations share the same rhythm and feelopacity-threshold - Fading elements should not linger below opacity 0.2; either fade fully or remain visiblemodal-motion - Modals/sheets should animate from their trigger source (scale+fade or slide-in) for spatial context (HIG, MD)navigation-direction - Forward navigation animates left/up; backward animates right/down — keep direction logically consistent (HIG)layout-shift-avoid - Animations must not cause layout reflow or CLS; use transform for position changesinput-labels - Visible label per input (not placeholder-only)error-placement - Show error below the related fieldsubmit-feedback - Loading then success/error state on submitrequired-indicators - Mark required fields (e.g. asterisk)empty-states - Helpful message and action when no contenttoast-dismiss - Auto-dismiss toasts in 3-5sconfirmation-dialogs - Confirm before destructive actionsinput-helper-text - Provide persistent helper text below complex inputs, not just placeholder (Material Design)disabled-states - Disabled elements use reduced opacity (0.38–0.5) + cursor change + semantic attribute (MD)progressive-disclosure - Reveal complex options progressively; don't overwhelm users upfront (Apple HIG)inline-validation - Validate on blur (not keystroke); show error only after user finishes input (MD)input-type-keyboard - Use semantic input types (email, tel, number) to trigger the correct mobile keyboard (HIG, MD)password-toggle - Provide show/hide toggle for password fields (MD)autofill-support - Use autocomplete / textContentType attributes so the system can autofill (HIG, MD)undo-support - Allow undo for destructive or bulk actions (e.g. "Undo delete" toast) (Apple HIG)success-feedback - Confirm completed actions with brief visual feedback (checkmark, toast, color flash) (MD)error-recovery - Error messages must include a clear recovery path (retry, edit, help link) (HIG, MD)multi-step-progress - Multi-step flows show step indicator or progress bar; allow back navigation (MD)form-autosave - Long forms should auto-save drafts to prevent data loss on accidental dismissal (Apple HIG)sheet-dismiss-confirm - Confirm before dismissing a sheet/modal with unsaved changes (Apple HIG)error-clarity - Error messages must state cause + how to fix (not just "Invalid input") (HIG, MD)field-grouping - Group related fields logically (fieldset/legend or visual grouping) (MD)read-only-distinction - Read-only state should be visually and semantically different from disabled (MD)focus-management - After submit error, auto-focus the first invalid field (WCAG, MD)error-summary - For multiple errors, show summary at top with anchor links to each field (WCAG)touch-friendly-input - Mobile input height ≥44px to meet touch target requirements (Apple HIG)destructive-emphasis - Destructive actions use semantic danger color (red) and are visually separated from primary actions (HIG, MD)toast-accessibility - Toasts must not steal focus; use aria-live="polite" for screen reader announcement (WCAG)aria-live-errors - Form errors use aria-live region or role="alert" to notify screen readers (WCAG)contrast-feedback - Error and success state colors must meet 4.5:1 contrast ratio (WCAG, MD)timeout-feedback - Request timeout must show clear feedback with retry option (MD)bottom-nav-limit - Bottom navigation max 5 items; use labels with icons (Material Design)drawer-usage - Use drawer/sidebar for secondary navigation, not primary actions (Material Design)back-behavior - Back navigation must be predictable and consistent; preserve scroll/state (Apple HIG, MD)deep-linking - All key screens must be reachable via deep link / URL for sharing and notifications (Apple HIG, MD)tab-bar-ios - iOS: use bottom Tab Bar for top-level navigation (Apple HIG)top-app-bar-android - Android: use Top App Bar with navigation icon for primary structure (Material Design)nav-label-icon - Navigation items must have both icon and text label; icon-only nav harms discoverability (MD)nav-state-active - Current location must be visually highlighted (color, weight, indicator) in navigation (HIG, MD)nav-hierarchy - Primary nav (tabs/bottom bar) vs secondary nav (drawer/settings) must be clearly separated (MD)modal-escape - Modals and sheets must offer a clear close/dismiss affordance; swipe-down to dismiss on mobile (Apple HIG)search-accessible - Search must be easily reachable (top bar or tab); provide recent/suggested queries (MD)breadcrumb-web - Web: use breadcrumbs for 3+ level deep hierarchies to aid orientation (MD)state-preservation - Navigating back must restore previous scroll position, filter state, and input (HIG, MD)gesture-nav-support - Support system gesture navigation (iOS swipe-back, Android predictive back) without conflict (HIG, MD)tab-badge - Use badges on nav items sparingly to indicate unread/pending; clear after user visits (HIG, MD)overflow-menu - When actions exceed available space, use overflow/more menu instead of cramming (MD)bottom-nav-top-level - Bottom nav is for top-level screens only; never nest sub-navigation inside it (MD)adaptive-navigation - Large screens (≥1024px) prefer sidebar; small screens use bottom/top nav (Material Adaptive)back-stack-integrity - Never silently reset the navigation stack or unexpectedly jump to home (HIG, MD)navigation-consistency - Navigation placement must stay the same across all pages; don't change by page typeavoid-mixed-patterns - Don't mix Tab + Sidebar + Bottom Nav at the same hierarchy levelmodal-vs-navigation - Modals must not be used for primary navigation flows; they break the user's path (HIG)focus-on-route-change - After page transition, move focus to main content region for screen reader users (WCAG)persistent-nav - Core navigation must remain reachable from deep pages; don't hide it entirely in sub-flows (HIG, MD)destructive-nav-separation - Dangerous actions (delete account, logout) must be visually and spatially separated from normal nav items (HIG, MD)empty-nav-state - When a nav destination is unavailable, explain why instead of silently hiding it (MD)chart-type - Match chart type to data type (trend → line, comparison → bar, proportion → pie/donut)color-guidance - Use accessible color palettes; avoid red/green only pairs for colorblind users (WCAG, MD)data-table - Provide table alternative for accessibility; charts alone are not screen-reader friendly (WCAG)pattern-texture - Supplement color with patterns, textures, or shapes so data is distinguishable without color (WCAG, MD)legend-visible - Always show legend; position near the chart, not detached below a scroll fold (MD)tooltip-on-interact - Provide tooltips/data labels on hover (Web) or tap (mobile) showing exact values (HIG, MD)axis-labels - Label axes with units and readable scale; avoid truncated or rotated labels on mobileresponsive-chart - Charts must reflow or simplify on small screens (e.g. horizontal bar instead of vertical, fewer ticks)empty-data-state - Show meaningful empty state when no data exists ("No data yet" + guidance), not a blank chart (MD)loading-chart - Use skeleton or shimmer placeholder while chart data loads; don't show an empty axis frameanimation-optional - Chart entrance animations must respect prefers-reduced-motion; data should be readable immediately (HIG)large-dataset - For 1000+ data points, aggregate or sample; provide drill-down for detail instead of rendering all (MD)number-formatting - Use locale-aware formatting for numbers, dates, currencies on axes and labels (HIG, MD)touch-target-chart - Interactive chart elements (points, segments) must have ≥44pt tap area or expand on touch (Apple HIG)no-pie-overuse - Avoid pie/donut for >5 categories; switch to bar chart for claritycontrast-data - Data lines/bars vs background ≥3:1; data text labels ≥4.5:1 (WCAG)legend-interactive - Legends should be clickable to toggle series visibility (MD)direct-labeling - For small datasets, label values directly on the chart to reduce eye traveltooltip-keyboard - Tooltip content must be keyboard-reachable and not rely on hover alone (WCAG)sortable-table - Data tables must support sorting with aria-sort indicating current sort state (WCAG)axis-readability - Axis ticks must not be cramped; maintain readable spacing, auto-skip on small screensdata-density - Limit information density per chart to avoid cognitive overload; split into multiple charts if neededtrend-emphasis - Emphasize data trends over decoration; avoid heavy gradients/shadows that obscure the datagridline-subtle - Grid lines should be low-contrast (e.g. gray-200) so they don't compete with datafocusable-elements - Interactive chart elements (points, bars, slices) must be keyboard-navigable (WCAG)screen-reader-summary - Provide a text summary or aria-label describing the chart's key insight for screen readers (WCAG)error-state-chart - Data load failure must show error message with retry action, not a broken/empty chartexport-option - For data-heavy products, offer CSV/image export of chart datadrill-down-consistency - Drill-down interactions must maintain a clear back-path and hierarchy breadcrumbtime-scale-clarity - Time series charts must clearly label time granularity (day/week/month) and allow switchingSearch specific domains using the CLI tool below.