Sistema de design visual
Quick Reference
A plataforma de documentação da A55 usa um sistema de design próprio. Quatro equipes — design de componentes UI, arquitetura de documentação, pesquisa de experiência do desenvolvedor e engenharia de framework — convergiram nestas decisões visuais. Todos os tokens, componentes e regras de layout descritos aqui estão implementados e em produção.
Tokens de design
Os tokens de design definem os valores visuais fundamentais. Eles garantem consistência entre modo claro, modo escuro e todos os componentes customizados.
| Token | Valor (claro) | Valor (escuro) | Finalidade |
|---|---|---|---|
| Azul primário | #2563eb | #60a5fa | Links, badges, item ativo na sidebar. O valor escuro atende WCAG AA. |
| Tipografia body | Inter | Inter | Padrão do Google Developer Docs. Sans-serif limpa e legível. |
| Tipografia código | JetBrains Mono | JetBrains Mono | Otimizada para legibilidade em code blocks. Sem ligaturas. |
| Raio do card | 12px | 12px | Consistente em cards, admonitions e education boxes. |
| Base de espaçamento | 4px | 4px | Todos os incrementos de espaçamento usam múltiplos de 4. |
| Largura da sidebar | 260px | 260px | Largura fixa seguindo o padrão de três colunas (Stripe/Twilio). |
| Largura máxima do conteúdo | 800px | 800px | Comprimento de linha legível para prosa técnica. |
Cores semânticas
| Nome | Valor | Uso |
|---|---|---|
--a55-success | #16a34a | Estados de sucesso, badges do método POST |
--a55-warning | #ca8a04 | Avisos, badges do método PUT |
--a55-danger | #dc2626 | Erros, badges do método DELETE |
--a55-info | #0891b2 | Callouts informativos |
--a55-text-muted | #64748b | Texto secundário, labels, timestamps |
Componentes MDX customizados
Cinco componentes customizados estendem o toolkit padrão do Docusaurus. Cada componente resolve um problema específico de documentação.
QuickReference
Um card no topo de cada página. Mostra o que a página cobre, por que é importante, tempo estimado de leitura, nível de dificuldade e pré-requisitos.
| Campo | Finalidade |
|---|---|
what | Resumo de uma linha sobre o conteúdo da página |
why | O motivo pelo qual você precisa desta página |
time | Tempo estimado de leitura |
difficulty | beginner, intermediate ou advanced |
prerequisites | Lista de páginas ou conceitos necessários antes |
Padrão visual: Borda esquerda azul accent. Grid responsivo. Micro-labels em maiúsculo. Você vê em três segundos o que a página cobre.
EducationBox
Uma caixa colapsável para conceitos de base. Desenvolvedores seniores ignoram. Desenvolvedores juniores expandem para aprender.
| Comportamento | Detalhe |
|---|---|
| Estado padrão | Colapsado |
| Toggle | Chevron animado que rotaciona ao clicar |
| Background | Tinta azul sutil a partir da cor primária |
| Conteúdo | Texto explicativo para conceitos como OAuth, idempotência ou segurança de dados de cartão |
Padrão visual: Colapsado por padrão. Background com tinta azul. Animação de chevron no toggle. Zero ruído visual para leitores experientes.
EndpointHeader
Uma barra com badge e path para cada página de API Reference. O método HTTP aparece como uma pílula colorida. O path do endpoint aparece em fonte monospace.
| Método | Cor do badge |
|---|---|
GET | Azul (#dbeafe / #1d4ed8) |
POST | Verde (#dcfce7 / #15803d) |
PUT | Amarelo (#fef3c7 / #92400e) |
DELETE | Vermelho (#fee2e2 / #991b1b) |
Padrão visual: Pílula colorida + path em monospace. Você reconhece o método HTTP instantaneamente sem precisar ler.
NextSteps
Dois ou três cards no rodapé de cada página. Cada card leva à próxima página lógica na jornada do desenvolvedor.
| Campo | Finalidade |
|---|---|
title | Nome curto da próxima página |
description | Uma frase sobre o que você faz ali |
to | Caminho do link |
Padrão visual: Hover com elevação + borda accent. Divulgação progressiva guia você adiante.
StepFlow
Passos numerados com indicador circular e linha conectora vertical. Construído para tutoriais e guias sequenciais.
| Elemento | Visual |
|---|---|
| Número do passo | Círculo azul com texto branco |
| Conector | Linha vertical entre os passos |
| Conteúdo | Bloco indentado abaixo de cada passo |
Padrão visual: Números dos passos em círculos azul primário. Linha vertical os conecta. A área de conteúdo é indentada. O último passo não tem linha ao final.
Princípios de layout
O layout segue padrões estabelecidos pela documentação do Stripe, Twilio e Adyen.
Layout de três colunas
| Coluna | Largura | Conteúdo |
|---|---|---|
| Sidebar esquerda | 260px | Árvore de navegação com categorias de seção |
| Conteúdo central | 800px máx. | Prosa, code blocks, tabelas |
| Coluna direita | Automática | Índice de conteúdo (links para headings) |
Regras de hierarquia visual
| Regra | Implementação |
|---|---|
| Item ativo na sidebar | Borda esquerda azul + background com tinta |
| Cabeçalhos de seção | Maiúsculo com letter-spacing na sidebar |
| Headings H2 | Borda superior separa cada seção visualmente |
| Linhas de tabela | Tinta ao passar o mouse para facilitar a leitura |
| Admonitions | Raio de 12px + sombra. Visíveis sem ser agressivos. |
| Code blocks | Borda de 1px separa código da prosa |
| Dark mode | Todos os tokens invertidos. Sombras com opacidade mais profunda. |
| Landing page | Texto gradiente no título. Grid de cards com elevação ao hover. |
Arquitetura da informação
A documentação migrou de uma estrutura plana para uma hierarquia baseada em jornada.
Antes (docs.a55.tech no ReadMe)
- 47 páginas sob uma única categoria "Getting Started"
- Sem hierarquia ou divulgação progressiva
- Páginas de API Reference exibiam JSON bruto do OpenAPI spec
- Página de introdução com conteúdo duplicado
Depois (Docusaurus)
44 páginas organizadas em seis seções claras:
| Seção | Páginas | Finalidade |
|---|---|---|
| Getting Started | 5 | Onboarding linear: credenciais, autenticação, ambiente, cartões de teste |
| Integration Methods | 8 | H2H, SDK v1/v2, Checkout Page, além de 3DS, DataOnly, Network Token |
| Payment Methods | 7 | Uma página por método com diagramas de lifecycle |
| Security and Features | 5 | Tokenização, Zero Auth, antifraude, assinaturas, performance |
| Reference | 6 | Códigos de status, códigos de resposta, matriz de provedores, BIN lookup, taxas de câmbio |
| API Reference | 13 | Cada endpoint com rotas corretas, tabelas de parâmetros e exemplos |
Correções técnicas
A migração do ReadMe para o Docusaurus corrigiu estes problemas:
| Problema no docs.a55.tech | Correção |
|---|---|
| 10 de 12 rotas de API com paths incorretos | Todas as rotas agora usam o prefixo /bank/wallet/ conforme o código-fonte |
Capture Charge usava POST | Corrigido para PUT para refletir o comportamento real da API |
Path do Zero Auth era /zero-auth/validate | Corrigido para /bank/wallet/zeroauth/ |
| Página de introdução com conteúdo duplicado | Duplicação removida |
| API Reference exibia JSON bruto do OpenAPI | Transformado em páginas legíveis com tabelas de parâmetros e exemplos |
Rotas de API verificadas
Cada path de endpoint na documentação corresponde ao código-fonte:
| Endpoint | Método | Path |
|---|---|---|
| Criar carteira | POST | /api/v1/bank/wallet/ |
| Consultar carteira | GET | /api/v1/bank/wallet/ |
| Criar cobrança | POST | /api/v1/bank/wallet/charge/ |
| Consultar cobrança | GET | /api/v1/bank/wallet/charge/ |
| Estornar cobrança | POST | /api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/ |
| Capturar cobrança | PUT | /api/v1/bank/wallet/charge/capture/ |
| Listar cobranças | GET | /api/v1/bank/wallet/charges/ |
| Consultar assinatura | GET | /api/v1/bank/wallet/subscription/ |
| Cancelar assinatura | DELETE | /api/v1/bank/wallet/subscription/{sub_uuid}/cancel/{wallet_uuid}/ |
| Criar link de pagamento | POST | /api/v1/bank/wallet/payment-link/ |
| Zero authorization | POST | /api/v1/bank/wallet/zeroauth/ |