Visual design system
Quick Reference
The A55 documentation platform uses a purpose-built design system. Four teams — UI component design, documentation architecture, developer experience research, and framework engineering — converged on these visual decisions. Every token, component, and layout rule described here is implemented and live.
Design tokens
Design tokens define the foundational visual values. They ensure consistency across light mode, dark mode, and all custom components.
| Token | Light value | Dark value | Purpose |
|---|---|---|---|
| Primary blue | #2563eb | #60a5fa | Links, badges, active sidebar items. Dark value meets WCAG AA contrast. |
| Body typeface | Inter | Inter | Google Developer Docs standard. Clean, highly legible sans-serif. |
| Code typeface | JetBrains Mono | JetBrains Mono | Optimized for code block readability. Ligature-free. |
| Card radius | 12px | 12px | Consistent across cards, admonitions, and education boxes. |
| Spacing base | 4px | 4px | All spacing increments use multiples of 4. |
| Sidebar width | 260px | 260px | Fixed width following the Stripe/Twilio three-column pattern. |
| Content max-width | 800px | 800px | Readable line length for technical prose. |
Semantic colors
| Name | Value | Usage |
|---|---|---|
--a55-success | #16a34a | Success states, POST method badges |
--a55-warning | #ca8a04 | Warnings, PUT method badges |
--a55-danger | #dc2626 | Errors, DELETE method badges |
--a55-info | #0891b2 | Informational callouts |
--a55-text-muted | #64748b | Secondary text, labels, timestamps |
Custom MDX components
Five custom components extend the standard Docusaurus toolkit. Each component solves a specific documentation problem.
QuickReference
A card at the top of every page. It shows what the page covers, why it matters, estimated reading time, difficulty level, and prerequisites.
| Field | Purpose |
|---|---|
what | One-line summary of the page content |
why | The reason a developer needs this page |
time | Estimated reading time |
difficulty | beginner, intermediate, or advanced |
prerequisites | List of pages or concepts the reader needs first |
Visual pattern: Left blue accent border. Responsive grid. Uppercase micro-labels. The developer sees in three seconds what the page covers.
EducationBox
A collapsible box for background concepts. Senior developers skip it. Junior developers expand it to learn.
| Behavior | Detail |
|---|---|
| Default state | Collapsed |
| Toggle | Animated chevron rotates on click |
| Background | Subtle blue tint from the primary color |
| Content | Explanatory text for concepts like OAuth, idempotency, or card data security |
Visual pattern: Collapsed by default. Blue-tinted background. Chevron animation on toggle. Zero visual noise for experienced readers.
EndpointHeader
A badge-and-path bar for every API reference page. The HTTP method appears as a colored pill. The endpoint path appears in monospace.
| Method | Badge color |
|---|---|
GET | Blue (#dbeafe / #1d4ed8) |
POST | Green (#dcfce7 / #15803d) |
PUT | Yellow (#fef3c7 / #92400e) |
DELETE | Red (#fee2e2 / #991b1b) |
Visual pattern: Color-coded pill + monospace path. Developers recognize the HTTP method instantly without reading.
NextSteps
Two or three cards at the bottom of every page. Each card links to the next logical page in the developer journey.
| Field | Purpose |
|---|---|
title | Short name of the next page |
description | One sentence about what the developer does there |
to | Link path |
Visual pattern: Hover elevation + border accent. Progressive disclosure guides the developer forward.
StepFlow
Numbered steps with a circular indicator and a vertical connecting line. Built for tutorials and sequential guides.
| Element | Visual |
|---|---|
| Step number | Blue circle with white text |
| Connector | Vertical line between steps |
| Content | Indented block under each step |
Visual pattern: Step numbers in primary blue circles. Vertical line connects them. The content area is indented. The last step has no trailing line.
Layout principles
The layout follows patterns established by Stripe, Twilio, and Adyen documentation.
Three-column layout
| Column | Width | Content |
|---|---|---|
| Left sidebar | 260px | Navigation tree with section categories |
| Center content | 800px max | Page prose, code blocks, tables |
| Right column | Auto | Table of contents (heading links) |
Visual hierarchy rules
| Rule | Implementation |
|---|---|
| Active sidebar item | Left blue border + tinted background |
| Section headers | Uppercase with letter-spacing in the sidebar |
| H2 headings | Top border separates each section visually |
| Table rows | Hover tint for scanability |
| Admonitions | 12px radius + shadow. Visible but not aggressive. |
| Code blocks | 1px border separates code from prose |
| Dark mode | All tokens inverted. Shadows use deeper opacity values. |
| Landing page | Gradient text on the title. Card grid with hover elevation. |
Information architecture
The documentation moved from a flat structure to a journey-based hierarchy.
Before (docs.a55.tech on ReadMe)
- 47 pages under a single "Getting Started" category
- No hierarchy or progressive disclosure
- API reference pages showed raw JSON from the OpenAPI spec
- Introduction page contained duplicated content
After (Docusaurus)
44 pages organized in six clear sections:
| Section | Pages | Purpose |
|---|---|---|
| Getting Started | 5 | Linear onboarding: credentials, auth, environment, test cards |
| Integration Methods | 8 | H2H, SDK v1/v2, Checkout Page, plus 3DS, DataOnly, Network Token |
| Payment Methods | 7 | One page per method with lifecycle diagrams |
| Security and Features | 5 | Tokenization, Zero Auth, anti-fraud, subscriptions, performance |
| Reference | 6 | Status codes, response codes, provider matrix, BIN lookup, FX rates |
| API Reference | 13 | Every endpoint with correct routes, parameter tables, and examples |
Technical corrections
The migration from ReadMe to Docusaurus fixed these issues:
| Problem in docs.a55.tech | Correction |
|---|---|
| 10 of 12 API routes had incorrect paths | All routes now use the /bank/wallet/ prefix matching the source code |
Capture Charge used POST | Corrected to PUT to match the actual API behavior |
Zero Auth path was /zero-auth/validate | Corrected to /bank/wallet/zeroauth/ |
| Introduction page had duplicated content | Duplication removed |
| API Reference showed raw JSON from OpenAPI | Transformed into readable pages with parameter tables and examples |
Verified API routes
Every endpoint path in the documentation matches the source code:
| Endpoint | Method | Path |
|---|---|---|
| Create wallet | POST | /api/v1/bank/wallet/ |
| Get wallet | GET | /api/v1/bank/wallet/ |
| Create charge | POST | /api/v1/bank/wallet/charge/ |
| Get charge | GET | /api/v1/bank/wallet/charge/ |
| Refund charge | POST | /api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/ |
| Capture charge | PUT | /api/v1/bank/wallet/charge/capture/ |
| List charges | GET | /api/v1/bank/wallet/charges/ |
| Get subscription | GET | /api/v1/bank/wallet/subscription/ |
| Cancel subscription | DELETE | /api/v1/bank/wallet/subscription/{sub_uuid}/cancel/{wallet_uuid}/ |
| Create payment link | POST | /api/v1/bank/wallet/payment-link/ |
| Zero authorization | POST | /api/v1/bank/wallet/zeroauth/ |