Communitygithub.com

coastdigitalgroup/coastai-skills

设计一个系统级错误状态(404、500、维护、离线)框架,以维护用户信任并提供清晰的恢复路径。

coastai-skills 是什么?

此技能提供了一套系统性的方法,用于设计网站中“不愉快的路径”——即系统级错误发生时的情况。与表单级验证或上下文横幅不同,该技能专门处理全页面或全站的状态,确保失败信息能够以清晰、富有同理心的方式传达,并提供明确的“出路”,从而防止因技术问题导致用户沮丧和流失。它支持多种平台(如Web应用),并针对404、500、维护模式和离线状态提供了详细的工作流程、决策规则和验证标准。核心目标是实现“人性优先”的沟通,避免技术术语,并通过视觉锚点、恢复路径和响应式适配来维持用户信任。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/coastdigitalgroup/coastai-skills/tree/HEAD/website-design/error-and-status-system

在你喜欢的 AI 中提问

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

文档

错误与状态系统

目的

错误与状态系统提供了一种方法论,用于设计网站的“不愉快路径”——即系统层面出现问题的时刻。与表单级验证或上下文横幅不同,该系统处理的是全页面或全站状态。它确保故障能够以清晰、富有同理心的方式进行沟通,并提供明确的“出路”,防止用户在遇到技术问题时感到沮丧和放弃。

用例

  • 404 未找到: 当用户访问一个不存在的URL时。
  • 500 服务器错误: 当关键的后端故障导致页面无法加载时。
  • 维护模式: 当站点因更新而有意下线时。
  • 离线状态: 用户在Web应用中失去连接时。
  • 拒绝访问 (403): 当用户无权查看特定资源时。

何时不使用

  • 表单验证: 对于字段级错误,请使用 form-design-system。
  • 上下文通知: 对于非阻塞更新或次要错误,请使用 banner-and-alert-system。
  • 空列表: 当页面加载正确但不包含任何数据时,请使用 empty-state-system。
  • 加载状态: 对于标准内容获取,请使用 skeleton-state-system。

输入

  1. 错误类型: 是客户端错误 (4xx)、服务器错误 (5xx) 还是系统状态 (维护)?
  2. 技术上下文: 系统能否在不泄露敏感数据的情况下解释 为什么 失败?
  3. 恢复路径: 用户最可能的下一步操作是什么?
  4. 品牌语气: 品牌语气是幽默、专业还是严格的技术风格?
  5. 系统约束: 离线状态是否需要支持特定的本地优先操作?

输出

  1. 状态页面结构: 定义了错误消息、视觉锚点和恢复操作的布局。
  2. 消息层级: 标题(发生了什么)和描述(下一步做什么)的标准。
  3. 恢复蓝图: 针对特定错误定制的链接、搜索输入或帮助资源的地图。
  4. 离线UI规范: 当连接丢失时界面如何变化的规则。

工作流程

1. 对故障严重性进行分类

确定错误的影响:

  • 低 (404/403): 局限于单个URL。网站运行正常。重点关注 重定向。
  • 高 (500): 系统范围或页面破坏性错误。网站正在挣扎。重点关注 安抚 和 支持。
  • 系统性 (维护): 计划性停机。重点关注 预期管理(例如,“下午2点恢复”)。
  • 连接性 (离线): 环境故障。重点关注 状态保存(例如,“更改已本地保存”)。

2. 建立恢复路径

每个错误页面必须有一个“出路”:

  • “首页”按钮: 绝对的最低要求。
  • 智能建议: 对于404错误,提供指向热门页面的链接或搜索栏。
  • “刷新”触发器: 对于5xx错误,提供一个显眼的重新尝试请求的途径。
  • 支持链接: 对于持续性问题,提供直接指向帮助中心或状态页面的路径。

3. 设计视觉结构

将 visual-hierarchy-system 应用于错误视图:

  • 视觉锚点: 使用品牌统一的插图或图标来缓和失败的影响。
  • 清晰标题: 使用“人性化”标题(例如,“我们找不到那个页面”)而不是仅仅显示状态码(“404错误”)。
  • 隐蔽的元数据: 保持技术代码(例如,错误 ID: 12345)小且低对比度,面向支持团队而非用户。

4. 应用“人性优先”消息规则

避免使用疏远用户的技术术语:

  • 糟糕: “500 内部服务器错误:对等连接重置。”
  • 良好: “我们这边出了点问题。我们现在正在努力修复。”
  • 糟糕: “404 资源未找到。”
  • 良好: “看来这个页面走错路了。”

5. 规划响应式适配

  • 全页面 vs. 模态框: 决定错误是否应占据整个视口(标准404/500)或显示为固定横幅(通常用于离线状态)。
  • 居中布局: 居中对齐内容通常是错误页面的最佳选择,因为它最小化了扫描努力,并强调了用户旅程中的“暂停”。

决策规则

  • “直接路径”规则: 绝不让错误页面成为死胡同。如果没有具体建议,始终包含“返回首页”和“搜索”选项。
  • 搜索-on-404: 如果站点有超过100个页面,404页面必须包含一个搜索栏。
  • 维护透明度: 如果处于维护模式,始终提供预计返回时间或指向状态页面的链接。
  • 离线持久性: 离线时,在视觉上“变灰”或禁用非功能性操作(例如,“提交”按钮)以防止数据丢失。

约束

  • 可访问性: 错误页面必须尽可能保留站点的全局导航和页脚,以提供熟悉的方向感。对于动态状态变化(如下线),使用 aria-live="assertive" 区域立即宣布变化。
  • 响应性: 错误页面必须尽可能具有弹性。避免使用可能因系统已经不堪重负而无法加载的重型资源。
  • 品牌一致性: 错误页面应看起来是站点的一部分,而不是通用的浏览器或服务器默认页面。

常见失败模式

  • “死胡同”: 没有链接的404页面,迫使用户使用浏览器的返回按钮或离开。
  • “术语墙”: 显示原始的堆栈跟踪或数据库错误,使用户困惑并可能泄露安全信息。
  • “责备游戏”: 暗示用户做错了什么的消息(例如,“您输入的URL无效”),而不是对发现失败承担责任。
  • 风格不匹配: 错误页面使用与站点其余部分不同的字体/颜色,使其看起来破损或恶意。

验证标准

  • 每个错误状态(404,500等)都有一个清晰、人类可读的标题。
  • 至少存在一个主要的恢复操作(例如,“返回首页”)。
  • 对于404页面,提供了搜索栏或热门链接以便发现。
  • 技术元数据(错误ID)存在但在层级中处于次要地位。
  • 连接状态变化(离线)通过ARIA实时区域宣布。
  • 视觉样式与核心品牌/设计系统保持一致。
  • 维护页面提供了“预计恢复”或“状态页面”链接。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for progressive disclosure using accordions, ensuring structural integrity, visual affordances, and accessibility across different content densities and devices.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for long-form content, managing readability, vertical rhythm, and information density to ensure a superior reading experience.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for informational elements that communicate state (Badges) and categorization (Tags) with clarity and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for non-overlay notifications, managing global announcements and contextual inline alerts to communicate system states without interrupting the user's flow.

coastdigitalgroup/coastai-skills

Design and implement a systematic, asymmetrical bento-grid layout framework to organize diverse content types cohesively while maintaining strict visual hierarchy, logical focus order, and responsive flexibility.

coastdigitalgroup/coastai-skills

Design a responsive, mobile-first bottom navigation bar and persistent action dock system for mobile websites and web applications, establishing spatial anchors, tab bar anatomy, badge indicators, thumb-zone ergonomics, safe area inset handling, active/inactive state contrast, and desktop responsive adaptation rules.

coastdigitalgroup/coastai-skills

Design a mobile-first bottom sheet overlay system with configurable detents, drag affordances, safe area padding, responsive desktop modal/popover adaptation, and WCAG AA accessibility compliance.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for secondary navigation trails that provide orientation, context, and one-click access to parent levels in deep information architectures.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for buttons and interactive triggers, managing visual hierarchy, variant logic, and action grouping to ensure clear intent and accessible interaction.

coastdigitalgroup/coastai-skills

Design a systematic framework for date and time selection, managing calendar grids, range pickers, and scheduling interfaces to ensure precision and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for modular content containers that maintain hierarchy, structural integrity, and action alignment across variable content and responsive viewports.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for horizontal discovery components, managing navigation affordances, scroll behavior, and accessibility to ensure effective content density without compromising usability.

coastdigitalgroup/coastai-skills

Design a systematic, highly accessible, and developer-friendly UI layout framework for code blocks, snippet showcases, multi-file code tabs, line-highlighting, diff views, and syntax token contrast in technical documentation and developer platforms.

coastdigitalgroup/coastai-skills

Design a systematic framework for global command menus (Cmd+K panels) that combines keyboard-driven navigation, command execution, and shortcut discovery into an accessible, responsive overlay.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for threaded conversations, managing nesting depths, action hierarchies, and community signaling to foster engagement and readability.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for side-by-side comparison interfaces, managing high attribute density and responsive complexity to support informed decision-making.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for user privacy, managing consent banners, preference centers, and persistent privacy controls to balance legal compliance with user trust.

coastdigitalgroup/coastai-skills

Design and implement a systematic, highly accessible, and responsive visual layout framework for conversational chat widgets, live chat boxes, and chatbot panels that ensures clear message scannability, native focus flow, and seamless mobile keyboard adaptation.

coastdigitalgroup/coastai-skills

Design a systematic, accessible, and high-conversion framework for custom select dropdowns and comboboxes, defining anatomy, states, search-filtering, and responsive mobile-adaptive patterns.

coastdigitalgroup/coastai-skills

Design and implement a systematic color palette that ensures WCAG 2.2 accessibility compliance. Trigger this skill when asked to define brand colors, create UI themes, or establish a visual system for a website.

相关技能