OpenHelp: o tour guiado que pertence ao seu produto

Existe um momento previsível na vida de todo produto: alguém decide que os usuários precisam de ajuda dentro da tela. A saída padrão é contratar uma plataforma de adoção, colar um script no head e desenhar o passo a passo num editor visual de terceiro. Funciona na primeira semana. O problema aparece um ano depois, quando o tour aponta para um botão que mudou de lugar, ninguém do time sabe onde ele foi configurado, e a assinatura vence em trinta dias. O OpenHelp nasceu dessa segunda semana.

O tour que ninguém consegue mudar

Plataformas de adoção de produto como Pendo, Appcues, WalkMe e Userpilot resolvem um problema real: permitem que time de produto crie passo a passo sem depender de time de engenharia. Essa é a proposta, e ela é honesta. Só que ela vem com três consequências que raramente entram na decisão de compra.

• O conteúdo do Help sai do repositório. Ele passa a viver no painel do fornecedor. Não entra em revisão de código, não versiona junto com a funcionalidade que descreve e não volta no git revert quando a funcionalidade é desfeita.
• O seletor é escrito uma vez e esquecido. O editor visual grava um seletor de CSS apontando para a interface daquele dia. Quando o componente é refatorado, o tour aponta para o vazio, e nada no processo de build avisa.
• Um script de terceiro no caminho crítico. Ele carrega em toda página, participa do orçamento de desempenho, tem acesso ao DOM inteiro e normalmente envia telemetria. É uma decisão de arquitetura tomada por conveniência.

A alternativa conhecida é usar uma biblioteca de tour, como Intro.js, Shepherd.js ou Driver.js. Melhora bastante: o conteúdo volta para o repositório e o script de terceiro sai. Ainda assim você adota o modelo mental de um motor pronto, herda o visual dele e passa a lutar contra o CSS dele sempre que o design do produto evolui.

O que é o OpenHelp

O OpenHelp é uma Skill para agentes de codificação que constrói, dentro do seu projeto, uma experiência de Help guiado com passo a passo, botão de ajuda contextual e narração por voz opcional. Ele não é um pacote que você instala e configura: ele é um método que um agente executa, e o resultado é código no seu repositório.

Na prática, o agente lê o projeto antes de escrever qualquer coisa. Descobre o framework, o gerenciador de pacotes, as convenções de componente, os tokens de estilo, o roteamento e se existe renderização no servidor. Depois adapta um motor mínimo a essas convenções, em vez de despejar um bloco genérico que destoa do resto.

O que fica no fim é previsível: uma definição de jornada separada do motor, um renderizador que respeita o design do produto, um botão de Help visível com nome acessível, e atributos dedicados nos elementos que a jornada aponta. Nada disso depende de servidor externo para funcionar.

Por que uma Skill e não uma biblioteca

Esta é a decisão de arquitetura que mais gera pergunta, e ela tem uma razão específica. Help guiado é a categoria de funcionalidade que mais varia entre projetos, porque ela toca simultaneamente o roteamento, o ciclo de vida dos componentes, o sistema de design e o texto do produto. Uma biblioteca precisa acomodar toda essa variação com opções de configuração, e é assim que bibliotecas de tour ficam grandes e ainda não servem ao seu caso.

Uma Skill inverte a relação. Em vez de trazer código pronto que precisa ser dobrado até caber, ela traz o conhecimento de como construir aquilo corretamente, e deixa o agente escrever a versão que se encaixa neste projeto. As invariantes viajam; a implementação nasce local.

Aspecto	Plataforma hospedada	Biblioteca de tour	Skill que gera código
Onde vive o conteúdo	Painel do fornecedor	No repositório	No repositório
Entra em revisão de código	Não	Sim	Sim
Visual	Tema do fornecedor	CSS da biblioteca	Tokens do próprio produto
Script de terceiro em produção	Sim	Não	Não
Custo recorrente	Assinatura	Nenhum	Nenhum
Quem mantém	Fornecedor	Comunidade da biblioteca	Seu time
Custo de saída	Alto, refazer tudo	Médio	Nenhum, o código já é seu

Vale ser justo com a coluna do meio: se o seu time não usa agente de codificação e não pretende usar, uma biblioteca de tour é a escolha sensata. O OpenHelp pressupõe que existe um agente no fluxo de trabalho, e essa premissa não vale para todo mundo.

Sobre qual agente escolher para este tipo de tarefa, a divisão que usamos está em Claude Code, Codex e Gemini no mesmo time. Para o OpenHelp em particular, o que mais pesa é a capacidade de ler o repositório inteiro antes de escrever, porque a qualidade do resultado vem de respeitar convenções que ninguém documentou.

Uma jornada útil tem de três a sete passos

A parte difícil de Help guiado não é técnica, é editorial. O erro mais comum é tentar apresentar o produto inteiro no primeiro acesso. Passo doze é visto por quase ninguém, e a partir do quarto ou quinto a taxa de abandono já é alta o suficiente para tornar o resto irrelevante.

A regra que a Skill impõe é estreita de propósito: uma jornada existe para um resultado, não para uma funcionalidade. A diferença aparece no enunciado.

• Jornada por funcionalidade, que não funciona: “conheça o menu lateral”, “veja os filtros”, “estes são os relatórios”. É um passeio pela interface, e ninguém pediu um passeio.
• Jornada por resultado, que funciona: “publique seu primeiro relatório”. Passa pelo menu, pelos filtros e pelo botão de publicar, mas o usuário atravessa isso perseguindo algo que ele queria.

Daí decorrem três consequências práticas. A primeira é que vários Helps curtos batem um Help longo, e cada um deve ser acionável no contexto em que faz sentido. A segunda é que o botão precisa estar visível sempre, e não só no primeiro acesso: a maior parte da consulta ao Help acontece na terceira semana, quando a pessoa tenta fazer algo que ainda não tinha feito. A terceira é que a conclusão precisa ficar registrada com versão, para que uma jornada reescrita possa ser exibida de novo sem incomodar quem já viu a antiga.

O alvo do passo, onde quase todo tour quebra

Se houver uma única coisa para levar deste artigo, é esta. Todo passo aponta para um elemento da tela, e a forma de apontar decide se o Help sobrevive ao próximo trimestre.

Três formas erradas, todas comuns:

• Classe gerada por ferramenta de build. Nomes com sufixo aleatório mudam a cada compilação. O seletor funciona hoje e falha no deploy de amanhã, sem erro em lugar nenhum.
• Texto visível. Apontar pelo conteúdo do botão quebra na primeira tradução, e quebra de novo quando alguém troca “Salvar” por “Concluir” numa revisão de copy.
• Profundidade de DOM. Caminhos com muitos níveis de descendente quebram quando alguém envolve a seção num contêiner novo, que é a refatoração mais banal que existe.

A forma certa é um atributo dedicado, no formato data-open-help="publicar-relatorio", colocado no elemento pela própria equipe que escreve o componente. Ele é explícito, é procurável no repositório inteiro e diz a quem for refatorar que aquele elemento tem um contrato.

Vale ainda separar alvo obrigatório de alvo opcional. Um passo que aponta para algo que só existe em certos planos ou perfis deve ser pulado em silêncio, e não travar a jornada inteira com erro.

Voz: três caminhos e um padrão

Narração é a parte do OpenHelp que mais chama atenção em demonstração e a que mais exige critério na decisão. Ela ajuda de verdade em produto usado com as mãos ocupadas, em público com dificuldade de leitura e em treinamento de equipe. Em software administrativo comum, costuma ser enfeite.

Caminho	Custo	Qualidade em português	Infraestrutura	Bom quando
Síntese do navegador	Nenhum	Varia por sistema e por aparelho	Nenhuma	Padrão, e o suficiente na maioria dos casos
Áudio pré-renderizado	Só o de gerar uma vez	Consistente entre aparelhos	Arquivos servidos como estáticos	Texto fixo, e a consistência importa
API hospedada	Por uso	Alta	Endpoint no próprio servidor	Narração dinâmica ou marca com voz própria

A síntese do navegador usa a Web Speech API, já presente nos navegadores atuais. Não custa nada, não envia dado para lugar nenhum e funciona sem configuração. A limitação é conhecida: a voz depende do sistema operacional do usuário, então a mesma jornada soa diferente em aparelhos diferentes.

O áudio pré-renderizado resolve a inconsistência. Como o texto da jornada é fixo, ele pode ser gerado uma vez e servido como arquivo estático. Modelos abertos de síntese, como o Kokoro, produzem português aceitável para esse uso sem custo por reprodução. É o meio termo que costuma ser esquecido nas duas pontas da discussão.

A API hospedada, com serviços como o Fish Audio, entra quando a narração precisa ser dinâmica ou quando a marca quer uma voz própria e reconhecível. Aqui há uma regra que não se negocia.

Duas regras finais sobre voz, ambas aprendidas na prática. A narração só começa depois de um gesto do usuário, porque navegador bloqueia reprodução automática e porque áudio inesperado num escritório é constrangedor. E o Help visível continua completo quando a voz falha: a narração acrescenta, nunca substitui o texto na tela.

A fronteira de dependência

O OpenHelp tem uma regra explícita sobre o que pode entrar no projeto, e ela existe porque a proposta se anula se a solução for trocar uma dependência grande por outra.

• Preferir o que o navegador já tem. TypeScript e CSS do próprio projeto, mais as APIs nativas. A maior parte do motor não precisa de nada além disso.
• Uma exceção prevista. Posicionamento robusto de elemento flutuante é genuinamente difícil, com viés de borda, rolagem e colisão. Uma biblioteca especializada nisso é aceitável quando o caso exige.
• Licenças permissivas apenas. MIT, BSD, ISC ou Apache 2.0, verificadas antes de entrar. Licença viral num pacote de interface cria problema jurídico que aparece tarde.
• Nada de motor completo nem de telemetria. Adotar um motor de tour pronto ou um SDK de análise anula a decisão inteira e traz de volta o problema original.

Há uma consequência de segurança nessa fronteira que vale explicitar: todo texto de produto é renderizado como texto, nunca como HTML injetado. Um motor de tour que aceita marcação no conteúdo do passo é uma superfície de ataque desnecessária, especialmente se algum dia o texto passar a vir de uma configuração editável.

O que quebra numa aplicação de página única

Aqui mora a diferença entre um tour que funciona na demonstração e um que funciona no produto. Aplicações modernas montam e desmontam a tela o tempo todo, e um Help ingênuo não sobrevive a isso.

1. Resolver a rota antes de procurar o alvo. Se o passo três está em outra tela, o Help navega até lá e só então procura o elemento. Procurar antes encontra nada e conclui erroneamente que o alvo sumiu.
2. Esperar com prazo definido. O elemento pode demorar a aparecer porque depende de uma requisição. A espera precisa ter limite, e o limite precisa terminar em mensagem útil, não em travamento silencioso.
3. Encerrar tudo ao sair. Navegação, desmontagem e saída da conta precisam cancelar ouvintes, observadores, cálculos de posição, narração e nós no DOM. Vazamento aqui produz balão órfão flutuando sobre a tela errada.
4. Proteger a renderização no servidor. window, document, armazenamento local e a API de fala não existem durante a renderização no servidor. Acesso sem proteção derruba a página inteira, e não só o Help.
5. Nunca iniciar sozinho mais de uma vez. Onboarding automático precisa de marca de conclusão com versão. Sem ela, todo recarregamento reapresenta o tour, que é a forma mais rápida de fazer o usuário odiar o recurso.

Acessibilidade não é etapa final

Um recurso de ajuda inacessível é uma contradição: ele existe justamente para quem está com dificuldade. Ainda assim, tour costuma ser a parte menos acessível de muitos produtos, porque é adicionado depois de tudo pronto.

O mínimo, que não é opcional: navegação por teclado com foco visível e ordem previsível, tecla de escape encerrando a qualquer momento, contraste que passa nos critérios da WCAG, funcionamento com a página ampliada e em tela estreita, anúncio correto para leitores de tela quando o passo muda, e respeito à preferência de movimento reduzido do sistema.

Um detalhe pequeno que muda muito: o balão nunca deve cobrir o elemento que ele está explicando. Parece óbvio escrito assim, e é o defeito mais frequente em telas estreitas, onde o espaço disponível força o posicionamento para cima do alvo.

O que faz um Help envelhecer bem

Help guiado tem uma característica cruel: ele apodrece em silêncio. Nenhum erro é lançado quando o passo aponta para um botão que mudou de nome, e o usuário que percebe raramente reporta. Ele apenas fecha e conclui que a ajuda do produto não presta.

Quatro práticas evitam isso, e todas são baratas quando adotadas desde o início.

• Alvos verificados no build. Um teste que falha quando um alvo obrigatório desaparece. É a diferença entre descobrir na hora e descobrir por reclamação.
• Jornada versionada. Alterar o conteúdo incrementa a versão, e quem já concluiu a anterior pode ver a nova. Sem versão, ou todo mundo revê tudo, ou ninguém revê nada.
• Texto perto do componente. Quanto mais perto do código que ele descreve, maior a chance de ser atualizado na mesma alteração que muda a tela.
• Revisão junto da funcionalidade. Mudou a tela do passo dois, o passo dois entra na mesma revisão de código. É processo, não ferramenta, e é o que mais funciona.

Onde o projeto está hoje

Cabe ser direto sobre a maturidade, porque isso muda a decisão de quem lê. O OpenHelp já foi usado com resultado em produto real, e o método descrito aqui é o que sobreviveu a esse uso. Ele não é uma proposta teórica.

Por outro lado, é um projeto no começo. Não existe ainda comunidade em volta, histórico de versões nem a quantidade de casos de uso que revela os problemas que só aparecem em escala. O repositório público e o pacote para instalação estão em preparação, e este artigo será atualizado com os endereços assim que estiverem no ar.

Quem adota agora ganha um Help que é código próprio, sem assinatura e sem script de terceiro, e aceita em troca ser quem encontra os primeiros problemas. Para produto pequeno ou médio essa troca costuma ser boa. Para uma operação que precisa de suporte contratado com prazo de resposta, ainda não é.

Quando não usar

Três situações em que a recomendação honesta é outra ferramenta.

Quando quem escreve o Help não é do time de produto de software. Se a pessoa que redige os passos precisa publicar sozinha, sem passar por deploy, uma plataforma com editor visual entrega exatamente isso e o OpenHelp não. Essa é uma diferença de fluxo de trabalho, não de qualidade.

Quando o produto precisa de segmentação e experimentação sofisticadas. Mostrar mensagens diferentes por plano, por coorte e por comportamento, com teste A e B em cima, é o que as plataformas de adoção fazem bem. Reconstruir isso do zero é um projeto grande e sem graça.

Quando o problema não é falta de ajuda. Se os usuários se perdem porque a interface é confusa, um tour vira curativo. Ele ensina a atravessar a confusão em vez de removê-la, e adia a correção que resolveria o problema de verdade. Vale desconfiar sempre que a resposta para “por que precisamos de um tour” for “porque essa tela é difícil”.

Perguntas frequentes

O OpenHelp funciona com qual framework?

Com qualquer frontend em JavaScript ou TypeScript. React, Vue, Svelte, Angular e JavaScript puro estão previstos no método. Como o agente lê o projeto antes de escrever, o resultado segue as convenções que já existem ali em vez de impor um padrão de fora.

Preciso pagar alguma coisa para usar?

O Help em si não tem custo recorrente, porque o que fica no projeto é código seu, sem serviço externo. Os únicos custos possíveis são o do agente de codificação que você já usa e, se optar por narração hospedada, o consumo dessa API. Os dois caminhos gratuitos de voz cobrem a maioria dos casos.

Dá para migrar de uma plataforma de adoção sem perder o conteúdo?

O texto dos passos é aproveitável e costuma ser a parte que deu mais trabalho. O que não migra são os seletores gravados no editor visual, que precisam virar atributos dedicados no código. Na prática a migração é uma boa oportunidade de cortar passos que ninguém completava.

A voz funciona em qualquer navegador?

A síntese nativa está presente nos navegadores atuais, mas as vozes disponíveis dependem do sistema operacional, então o resultado varia. Quando a consistência importa, áudio pré-renderizado resolve, porque todo mundo ouve exatamente o mesmo arquivo. Em qualquer caso, o Help visível continua completo sem som.

Quanto código isso adiciona ao projeto?

O motor é pequeno, na ordem de algumas centenas de linhas, mais o CSS e a definição das jornadas. O peso real depende de quantas jornadas existem e de haver ou não posicionamento avançado. É bem menos do que a maioria das pessoas espera, e essa foi a constatação que originou o projeto.

Preciso de agente de codificação para usar?

É a forma prevista, porque o OpenHelp é uma Skill que instrui um agente. Um desenvolvedor pode ler o método e implementar à mão, já que não há mágica no conteúdo, mas o ganho de tempo vem justamente de o agente adaptar tudo ao projeto sozinho.

Como sei se as pessoas estão concluindo a jornada?

O motor conhece os eventos de início, avanço, cancelamento e conclusão. Você conecta esses eventos à análise que o produto já usa, em vez de instalar mais um SDK. Quem cancela e em qual passo é a métrica mais útil, porque aponta exatamente onde o texto está confuso.

Serve para documentação do produto?

Não, e misturar as duas coisas piora as duas. Documentação é consultada fora do fluxo, tem busca e profundidade. Help guiado acontece dentro da tela, no momento da dúvida, e precisa ser curto. Os dois convivem, e o passo final de uma jornada é um bom lugar para levar à documentação.

O que acontece se o elemento do passo não existir?

Depende de como o passo foi declarado. Alvo opcional é pulado em silêncio, o que é o comportamento certo para elementos que só aparecem em certos planos. Alvo obrigatório encerra com mensagem útil, e idealmente já teria sido detectado por um teste antes de chegar em produção.

Posso contribuir com o projeto?

Sim, e é justamente o que falta neste momento. Enquanto o repositório público não está no ar, o caminho é o contato direto pelo site. Relato de caso de uso em framework diferente do que já foi testado é a contribuição mais valiosa nesta fase.

Próximo passo

Se o seu produto tem um tour hoje, faça um teste de cinco minutos: abra a aplicação, rode o tour inteiro e conte quantos passos apontam para o lugar certo. Depois procure no repositório onde esse conteúdo está guardado. As duas respostas costumam ser mais desconfortáveis do que se espera, e elas dizem se vale trazer o Help para dentro.

Continuando pelo blog: Claude Code, Codex e Gemini no mesmo time trata de qual agente usar em cada tipo de tarefa, e Agente ou automação ajuda a decidir quanto de decisão vale delegar à máquina.

Fontes e leitura

• MDN Web Docs, Web Speech API, base da narração sem infraestrutura.
• W3C, WCAG 2.2, critérios de teclado, foco, contraste e movimento reduzido.
• MDN Web Docs, atributos data, a forma padrão de marcar um elemento com contrato.
• Open Source Initiative, licenças aprovadas, para a verificação de licença citada na fronteira de dependência.
• Especificação do Model Context Protocol, contexto do ecossistema de agentes em que a Skill roda.