视觉设计系统
Quick Reference
WhatA55 文档的设计系统和视觉决策
Why了解定义每个页面的令牌、组件和布局原则
Reading Time8 分钟
Difficulty初级
A55 文档平台使用专门构建的设计系统。四个团队分别是 UI 组件设计、文档架构、开发者体验研究和框架工程。他们已就这些视觉决策达成共识。本页描述的所有令牌、组件和布局规则均已实现并上线。
设计令牌
设计令牌（Design Token）定义颜色、间距、字体等基础视觉值。它们统一浅色模式与深色模式的表现。所有自定义组件也遵循同一套令牌。
| 令牌 | 浅色值 | 深色值 | 用途 |
|---|---|---|---|
| 主色蓝 | #2563eb | #60a5fa | 链接、徽章、侧边栏活动项。深色值满足 WCAG（网页内容无障碍指南） AA 对比度。 |
| 正文字体 | Inter | Inter | Google Developer Docs 标准字体。清晰、高度可读的无衬线字体。 |
| 代码字体 | JetBrains Mono | JetBrains Mono | 针对代码块可读性优化。无连字。 |
| 卡片圆角 | 12px | 12px | 在卡片、提示框和教育框中保持一致。 |
| 间距基准 | 4px | 4px | 所有间距增量使用 4 的倍数。 |
| 侧边栏宽度 | 260px | 260px | 遵循 Stripe/Twilio 三栏布局模式的固定宽度。 |
| 内容最大宽度 | 800px | 800px | 技术文章的可读行宽。 |
语义颜色
| 名称 | 值 | 用途 |
|---|---|---|
--a55-success | #16a34a | 成功状态、POST 方法徽章 |
--a55-warning | #ca8a04 | 警告、PUT 方法徽章 |
--a55-danger | #dc2626 | 错误、DELETE 方法徽章 |
--a55-info | #0891b2 | 信息提示 |
--a55-text-muted | #64748b | 次要文本、标签、时间戳 |
自定义 MDX 组件
五个自定义组件扩展了 Docusaurus 的标准工具包。每个组件解决一个特定的文档问题。
QuickReference
每个页面顶部的卡片。显示页面内容、重要性、预计阅读时间、难度级别和前置条件。
| 字段 | 用途 |
|---|---|
what | 页面内容的一行摘要 |
why | 开发者需要此页面的原因 |
time | 预计阅读时间 |
difficulty | beginner、intermediate 或 advanced |
prerequisites | 读者需要的前置页面或概念列表 |
视觉模式： 左侧蓝色强调边框。响应式网格。大写微标签。开发者在三秒内即可了解页面涵盖的内容。
EducationBox
用于背景概念的可折叠框。高级开发者跳过。初级开发者展开学习。
| 行为 | 详情 |
|---|---|
| 默认状态 | 折叠 |
| 切换 | 点击时带动画的箭头旋转 |
| 背景 | 基于主色的淡蓝色调 |
| 内容 | 对 OAuth、幂等性或卡数据安全等概念的说明文字 |
视觉模式： 默认折叠。蓝色调背景。切换时带箭头动画。对有经验的读者来说零视觉噪音。
EndpointHeader
每个 API 参考页面的徽章和路径栏。HTTP 方法显示为彩色药片形状。端点路径以等宽字体显示。
| 方法 | 徽章颜色 |
|---|---|
GET | 蓝色（#dbeafe / #1d4ed8） |
POST | 绿色（#dcfce7 / #15803d） |
PUT | 黄色（#fef3c7 / #92400e） |
DELETE | 红色（#fee2e2 / #991b1b） |
视觉模式： 彩色药片 + 等宽路径。开发者无需阅读即可立即识别 HTTP 方法。
NextSteps
每个页面底部的两到三张卡片。每张卡片链接到开发者旅程中的下一个逻辑页面。
| 字段 | 用途 |
|---|---|
title | 下一个页面的简短名称 |
description | 描述开发者在该页面要做什么的一句话 |
to | 链接路径 |
视觉模式： 悬停时提升 + 边框强调。渐进式披露引导开发者前进。
StepFlow
带有圆形指示器和垂直连接线的编号步骤。为教程和顺序指南而构建。
| 元素 | 视觉效果 |
|---|---|
| 步骤编号 | 蓝色圆形，白色文字 |
| 连接器 | 步骤间的垂直线 |
| 内容 | 每个步骤下方的缩进区块 |
视觉模式： 步骤编号在主色蓝色圆形中。垂直线连接各步骤。内容区域缩进。最后一个步骤没有尾部线条。
布局原则
布局遵循 Stripe、Twilio 和 Adyen 文档建立的模式。
三栏布局
| 列 | 宽度 | 内容 |
|---|---|---|
| 左侧边栏 | 260px | 包含分类的导航树 |
| 中间内容 | 最大 800px | 页面文本、代码块、表格 |
| 右侧列 | 自动 | 目录（标题链接） |
视觉层次规则
| 规则 | 实现方式 |
|---|---|
| 侧边栏活动项 | 左侧蓝色边框 + 着色背景 |
| 分类标题 | 侧边栏中大写并加大字间距 |
| H2 标题 | 顶部边框在视觉上分隔每个部分 |
| 表格行 | 悬停时着色，便于扫读 |
| 提示框 | 12px 圆角 + 阴影。醒目但不突兀。 |
| 代码块 | 1px 边框将代码与文本分隔 |
| 深色模式 | 所有令牌反转。阴影使用更深的透明度值。 |
| 着陆页 | 标题使用渐变文字。卡片网格悬停时提升。 |
信息架构
文档从扁平结构迁移到基于旅程的层次结构。
迁移前（ReadMe 上的 docs.a55.tech）
- 47 个页面归在单一的"快速入门"分类下
- 没有层次结构或渐进式披露
- API 参考页面显示 OpenAPI 规范的原始 JSON
- 介绍页面包含重复内容
迁移后（Docusaurus）
44 个页面组织为六个清晰的部分：
| 部分 | 页数 | 用途 |
|---|---|---|
| 快速入门 | 5 | 线性入门引导：凭证、身份验证、环境、测试卡 |
| 集成方式 | 8 | H2H、SDK v1/v2、Checkout Page，以及 3DS、DataOnly、Network Token |
| Payment Methods | 7 | 每种支付方式一个页面，含生命周期图 |
| 安全与功能 | 5 | 令牌化、Zero Auth（零额授权）、反欺诈、订阅、性能 |
| Reference | 6 | 状态码、响应码、提供商矩阵、BIN 查询、汇率 |
| API 参考 | 13 | 每个端点均包含正确路由、参数表和示例 |
技术修正
从 ReadMe 迁移到 Docusaurus 修复了以下问题：
| docs.a55.tech 中的问题 | 修正 |
|---|---|
| 12 个 API 路由中有 10 个路径错误 | 所有路由现已使用与源代码一致的 /bank/wallet/ 前缀 |
Capture Charge 使用 POST | 已修正为 PUT，与实际 API 行为一致 |
Zero Auth 路径为 /zero-auth/validate | 已修正为 /bank/wallet/zeroauth/ |
| 介绍页面包含重复内容 | 已删除重复内容 |
| API 参考显示 OpenAPI 原始 JSON | 已转换为包含参数表和示例的可读页面 |
已验证的 API 路由
文档中的每个端点路径均与源代码一致：
| 端点 | 方法 | 路径 |
|---|---|---|
| 创建钱包 | POST | /api/v1/bank/wallet/ |
| 查询钱包 | GET | /api/v1/bank/wallet/ |
| 创建收费 | POST | /api/v1/bank/wallet/charge/ |
| 查询收费 | GET | /api/v1/bank/wallet/charge/ |
| 退款 | POST | /api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/ |
| 扣款确认 | POST | /api/v1/bank/wallet/charge/capture/ |
| 列出收费记录 | GET | /api/v1/bank/wallet/charges/ |
| 查询订阅 | GET | /api/v1/bank/wallet/subscription/ |
| 取消订阅 | DELETE | /api/v1/bank/wallet/subscription/{sub_uuid}/cancel/{wallet_uuid}/ |
| 创建支付链接 | POST | /api/v1/bank/wallet/payment-link/ |
| 零额授权 | POST | /api/v1/bank/wallet/zeroauth/ |