Como construímos o QuickUse Calculator

Cada dólar, real, peso, porcentagem e basis point do site é calculado com matemática decimal de precisão arbitrária via biblioteca decimal.js. Nunca usamos float JavaScript pra dinheiro. Aritmética de ponto flutuante acumula erro de jeitos imperceptíveis em exemplos pequenos e catastróficos em escala — faça round-trip de uma contribuição mensal de R$ 1.000 ao longo de 30 anos de juros compostos e o saldo final flutua centenas de reais dependendo da ordem das operações.

Não é preocupação teórica. O bug do míssil Patriot, o bug do índice da bolsa de Vancouver, e uma cauda longa de overpayments em sistemas de folha de pagamento têm origem em uso indevido de ponto flutuante binário em domínio financeiro. Recusamos herdar essa classe de bug.

Toda tabela fiscal, limite de contribuição, teto de FGTS, faixa de IRPF e alíquota legal do site mora em arquivo TypeScript com header que nomeia a URL da fonte oficial, a data da última verificação e a data da próxima revisão. Não existe "número mágico" solto no código. Se um número governa o resultado, ele está em tabela versionada com nota de rodapé.

Quando você vê "R$ 7.786,02 — teto INSS 2026" numa calculadora previdenciária, o comentário-fonte abaixo nomeia a Portaria SEPRT correspondente, linka, e dá a data de verificação. Vale o mesmo pra faixas IRPF, multas FGTS, alíquotas ISS municipais, e qualquer outro input vindo de tabela governamental.

Tabelas fiscais mudam todo ano. Limites de contribuição se ajustam pela inflação. Salário-mínimo de São Paulo se move em cadência diferente do federal. Tratamos dado regulatório como infraestrutura viva: cada arquivo regulatório do site tem data de "próxima revisão", e o sistema de build sinaliza arquivos vencidos quando a janela fecha.

Em cada update anual, refazemos a busca da fonte oficial via web search em vez de confiar na memória do modelo ou no valor do ano passado, porque valores de tabela mudam de jeitos não-óbvios e modelos de linguagem treinados com knowledge cutoff vão alucinar silenciosamente. O git history registra o diff: qual valor mudou, quando, contra qual fonte.

Calculadoras universais (juros compostos, IMC, financiamento) saem em inglês e português brasileiro. Calculadoras país-específicas (IRPF pra Brasil, 401(k) pra EUA) ficam só no locale onde se aplicam, com slug naturalmente não-traduzido. Não existe etapa de tradução automática. Toda página em português é editada por humano pra que idiomas, termos regionais (rescisão, MEI, salário-mínimo) e formatação monetária funcionem certo. Vale igual pra inglês: brasileiro escrevendo sobre folha americana usa termo certo (FICA, FUTA, W-2) em vez de tradução literal.

Widget de calculadora sozinho não é página útil. Toda calculadora do site sai com explicação escrita de como a matemática funciona, pelo menos um exemplo trabalhado, dois ou três cenários práticos com números, seção "quando NÃO usar essa calculadora", FAQ de cinco a oito perguntas comuns, e lista de fontes citadas. Piso editorial é cerca de 1500 palavras de prosa original por calculadora. Abaixo disso, tratamos a página como rascunho, não referência.

Não é word count gratuito. Cada seção responde dúvida real do leitor, escrita da perspectiva de quem realmente pensou em quando a fórmula quebra. Exemplos trabalhados usam números que pessoa real reconhece — financiamento de R$ 400 mil, não de R$ 5 milhões.

Toda calculadora e todo post do site tem autor nomeado e revisor nomeado, ambos linkáveis a página de perfil que lista bio, expertise e credenciais. Handles de equipe editorial (QuickUse Editorial — Brasil, QuickUse Editorial — US) são declarados abertamente como assinaturas de equipe, não apresentados como indivíduos fictícios. Não usamos avatares gerados por IA que possam ser confundidos com pessoa real.

Quando o revisor é credenciado (contador com CRC ativo, CPA, CFP), a credencial aparece ao lado do byline. Quando o slot está reservado pra colaborador credenciado futuro, isso também é declarado. Honestidade sobre autoria é a fundação do E-E-A-T (Experience, Expertise, Authoritativeness, Trust), e tratamos como inegociável.

Você está lendo. Esta página é o contrato entre o site e seus leitores. Se a gente faz algo diferente do que está escrito aqui, a página está errada e a gente quer atualizar.

Antes de escrever uma linha de código, o colaborador lê a lei subjacente, a norma ou a referência canônica. Pra calculadora trabalhista brasileira isso significa ler os artigos da CLT relevantes e qualquer jurisprudência subsequente que mude materialmente o cálculo. Pra calculadora fiscal americana, significa ler a IRS Publication relevante e o boletim do DOL estadual aplicável. Pra calculadora de saúde, significa ler o paper original revisado por pares da fórmula (Mifflin-St Jeor pra TMB, variantes Harris-Benedict, etc.) — não um explicador de segunda mão.

A matemática é implementada como função pura em TypeScript com todos os valores monetários e percentuais tipados como instâncias decimal.js Decimal. Sem console.log, sem efeito colateral, sem acesso a DOM no compute. Isso torna a função testável e reutilizável.

Toda função de cálculo tem arquivo de teste com pelo menos três casos: cenário de livro com resposta conhecida, edge case (principal zero, contribuição máxima, aposentadoria na idade legal mínima), e comparação contra a calculadora que o próprio órgão regulador publica. Pra calculadoras fiscais brasileiras, isso frequentemente significa testar contra o simulador da Receita Federal. Pra previdência americana, contra exemplo de worksheet do IRS. A suite de testes precisa passar antes de qualquer trabalho de UI começar.

O autor escreve a prosa em volta da calculadora: introdução, explicação da fórmula, exemplo trabalhado, cenários práticos, quando-não-usar, FAQ, fontes. O rascunho é escrito pra leitor que acabou de pesquisar o tema e tem aproximadamente formação matemática de ensino médio. Sem jargão sem desempacotamento imediato em linguagem clara.

Pra calculadoras universais, editor humano traduz o conteúdo editorial para o segundo locale, adaptando idiomas e unidades em vez de traduzir literalmente. Exemplos monetários trocam — exemplo americano usa $300.000; versão brasileira usa R$ 1,2 milhão pra comparação equivalente.

Revisor nomeado com expertise relevante (ou handle de equipe editorial enquanto colaborador credenciado não é onboardado) revisa a matemática, os exemplos trabalhados, as citações de fonte e a linguagem do disclaimer. O revisor assina explicitamente. Nome dele e data da revisão aparecem no selo "Revisado por" abaixo do título da calculadora.

Rascunhos editoriais escritos com ajuda de ferramentas de pesquisa passam por etapa de humanização que remove marcadores de texto-IA — estrutura previsível de parágrafo, vocabulário padrão ("delve", "robusto", "abrangente"), templates tese-suporte-conclusão, listas com exatos três itens perfeitamente paralelos. Rascunhos que sobrevivem ao humanizer com o conteúdo dataístico intacto (números, citações, datas) viram a versão publicada.

Toda página tem como meta Lighthouse 95+ em Performance, Acessibilidade, Best Practices e SEO. Todo input tem label explícito. Todo elemento interativo é navegável por teclado. Contraste de cor atende WCAG AA. A região de resultado usa aria-live pra que leitores de tela anunciem mudança quando a calculadora atualiza.

A página vai ao ar via Vercel. Monitoramos erros em runtime via Sentry e anomalias de tráfego via analytics da hospedagem. Se um deploy introduz regressão, fazemos rollback; não tratamos pela frente ao custo de deixar número errado no ar por horas.

Quando o IRS anuncia limites de contribuição 2027, a gente adiciona entrada 2027 no arquivo de tabela relevante — não sobrescrevemos a entrada 2026. Cálculos históricos continuam auditáveis. Usuário rodando "what-if" com limites do ano passado recebe o número certo do ano passado. Query nova recebe o ano corrente por default.

Cada arquivo regulatório tem comentário de header declarando a URL da fonte oficial, a data em que os valores foram verificados pela última vez contra essa fonte, e a data da próxima revisão agendada. Arquivos vencidos são sinalizados em CI. Esse é o processo mínimo necessário pra evitar o modo de falha mais comum em sites de finanças: número velho parecendo oficial.

Quando colaborador (humano ou assistido por LLM) atualiza valor regulatório, o fluxo exige buscar a fonte oficial via web search em vez de confiar no dado de treino ou no arquivo do ano passado. Modelos de linguagem produzem com confiança valores errados pra limite 401(k) do ano que vem, taxa Selic atual ou salário-mínimo 2026 de algum estado, porque esses valores mudam depois do cutoff de treino do modelo. A etapa de verificação pega isso antes do merge.

Quando valor regulatório muda entre anos, o commit do git nomeia a URL da fonte e o diff. Esse é o trilho de auditoria. Já consideramos publicar changelog em página pública pro leitor, pra mudanças materiais; por enquanto o git history é o registro canônico.

Em 2026 lançamos uma calculadora de payroll americana com taxa NJ Family Leave Insurance de 0,432%. O dono do site percebeu que a alíquota publicada de 2026 caiu pra 0,23% — o valor original era correto pra ano anterior, não pro ano corrente. Hot-fix em 24h, adicionado à suite de testes de regressão, e a etapa de verificação no header do arquivo foi apertada pra que essa classe de bug apareça na próxima revisão anual. Documentamos aqui porque maturidade de processo é construída lembrando os fracassos, não só os sucessos.