hlibsuslov/telegram-bot-ui

Telegram Bot UI

Skill portável e independente de SDK para o ciclo de vida completo da interface de usuário de um bot do Telegram: auditoria → mapa de telas/estados → design de texto, botões e navegação → implementação → migração → testes → documentação.

Um bot do Telegram não possui CSS nem mecanismo de layout. Sua interface inteira é composta por cinco elementos: texto da mensagem, formatação, teclados, o chrome do chat (comandos, botão de menu, deep links) e as transições entre estados. Esta skill trata todos os cinco como uma única superfície de design.

Propósito

Ajudar um agente a tornar a interface de um bot clara, consistente e segura para modificar: escolher o que uma tela diz e como diz; rotular, agrupar, ordenar, colorir e dispor botões; projetar a navegação entre telas e estados; manter cada tela consistente com o resto do bot; preservar a localização intacta; e renderizar corpos de mensagem com o formato mais rico que couber — em qualquer idioma e qualquer SDK do Telegram, sem quebrar handlers ou lógica de negócio existentes.

Quando usar

• Trabalho de interface: "melhorar a UX/UI do bot", "redesenhar este menu", "o teclado está sobrecarregado", "os usuários não entendem esta tela", "adicionar um botão voltar", "agrupar estas ações", "destacar a ação principal".
• Botões e teclados: teclados inline, teclados de resposta, rótulos de botões, ordem e disposição dos botões, cores style, icon_custom_emoji_id com emoji personalizado, botões Web App / URL / copiar texto / switch-inline, ForceReply, remoção de teclado, paginação e navegação de volta.
• Texto e microcópia: reescrever mensagens do bot, títulos, legendas, prompts, confirmações, estados de erro e vazio, tom e extensão, uso de emoji.
• Chrome do chat: lista /commands e escopos, botão de menu, /start e deep links, experiência de primeiro uso.
• Feedback dinâmico: respostas de IA em streaming (sendMessageDraft, sendRichMessageDraft, <tg-thinking>), barras de progresso, status "digitando", carregadores de botões, "o bot parece travado enquanto processa".
• Personalização e links: cumprimentar usuários pelo nome com segurança, dicas de localidade, botões de URL vs links inline, previews de links, deep links, menções.
• Consistência: a mesma ação nomeada de três formas diferentes, botões voltar que existem apenas em algumas telas, estados incompatíveis após uma edição.
• Renderização de mensagens: HTML / MarkdownV2 / MessageEntity, emoji personalizado em texto, legendas, tabelas e Mensagens Ricas, opções link-preview / silent / protected, divisão de mensagens longas, rascunhos em streaming, edição, posts de canal, localização e RTL, can't parse entities, mensagens quebradas ou muito grandes.

Quando NÃO usar

Lógica do bot que não aparece na interface: infraestrutura de webhook, processamento de pagamentos, autorização, bancos de dados e migrações, administração de grupos e lógica de moderação, scraping, pipelines de análise, internos do Mini App (sua própria UI HTML/CSS é trabalho comum de front-end web — esta skill cobre apenas a superfície do lado do Telegram: o botão ou menu que o abre). Também não é para arquivos Microsoft .rtf.

Terminologia — não confunda estes

• Teclado inline ≠ teclado de resposta. InlineKeyboardMarkup é anexado a uma mensagem específica e envia callback_query / abre URLs. ReplyKeyboardMarkup substitui o teclado de letras do usuário e envia texto como uma mensagem normal. Classes de botão diferentes, UX diferente.
• style não é um valor de cor. É exatamente um de primary, success, danger. O Telegram não possui cores de botão HEX/RGB/CSS.
• icon_custom_emoji_id não é um file_id, não é um nome de pacote de emoji, não é um link e não é um emoji Unicode. É o ID de um emoji personalizado específico.
• Texto Rico do Telegram NÃO é RTF do Microsoft. Nunca chame Mensagens Ricas de "RTF".
• Markdown Rico ≠ MarkdownV2. MarkdownV2 é um parse_mode para mensagens comuns com escape estrito. Markdown Rico é a sintaxe de documento para Mensagens Ricas.
• HTML Rico ≠ HTML arbitrário de navegador. Apenas o conjunto de tags suportado pelo Telegram.
• Editar um teclado ≠ reenviar uma tela. editMessageReplyMarkup e editMessageText atualizam no lugar; enviar uma nova mensagem empilha telas.

Política de fonte da verdade

Confie nesta ordem:

1. Documentação oficial atual do Telegram (Bot API, Bot Features, páginas de formatação, blog oficial).
2. Changelog oficial da Bot API.
3. Documentação do SDK realmente instalado no projeto.
4. Código fonte do SDK.
5. Rastreador de issues do SDK.
6. Artigos de terceiros — apenas contexto suplementar.

Re-verifique a documentação oficial antes de agir quando: a tarefa tocar em novas APIs; a data atual for posterior à data da "última verificação" em references/official-sources.md; a versão da Bot API do projeto for desconhecida; a documentação do SDK contradizer a Bot API; você encontrar um tipo/campo desconhecido; ou o usuário pedir "as capacidades mais recentes". Esta skill não está congelada na Bot API 10.2 — se o Telegram lançou uma versão mais recente, use-a. Portões de versão relevantes para UI: references/ui-changelog.md.

Fluxo de trabalho principal (audite antes de redesenhar)

1. Leia as instruções do projeto (AGENTS.md / CLAUDE.md / README / docs).
2. Detecte idioma, framework, SDK do Telegram e versões exatas.
3. Determine a versão da Bot API que o SDK realmente suporta — isso decide se style e icon_custom_emoji_id são acessíveis.
4. Construa um mapa de telas/estados: cada mensagem que o usuário pode ver, cada teclado, cada callback_data, cada comando, cada transição (references/navigation-and-flows.md).
5. Classifique cada tela: entrada / menu / etapa de formulário / confirmação / resultado / erro / vazia / notificação.
6. Identifique os defeitos reais de UX (não invente trabalho): rótulos ambíguos, teclados sobrecarregados, becos sem saída, nomenclatura inconsistente, ações destrutivas a um toque de distância, strings não localizadas, corpos ilegíveis.
7. Projete a correção: texto primeiro, depois estrutura, depois layout, depois cor/emoji — nessa ordem. Cor é a última camada, nunca a solução para um rótulo ruim.
8. Verifique o suporte do SDK para cada campo que você planeja usar (references/sdk-compatibility.md).
9. Implemente no estilo e utilitários existentes do projeto (não duplique seus construtores de teclado).
10. Preserve callback_data, URLs, deep links, roteamento de handlers e chaves de localização, a menos que o usuário tenha pedido explicitamente para alterá-los.
11. Adicione um caminho de fallback e mantenha clientes antigos utilizáveis (references/errors-and-fallbacks.md).
12. Adicione testes com a infraestrutura de teste existente do projeto (references/testing-playbook.md).
13. Execute lint / typecheck / testes / verificações de fumaça aplicáveis do projeto.
14. Relate: mapa de telas, o que mudou e por quê, o que foi deliberadamente deixado de lado, limites e evidências de verificação.

Não escreva código de implementação antes das etapas 1 a 6 estarem completas.

As cinco camadas de UI (projete nesta ordem)

#	Camada	Pergunta que responde	Referência
1	Palavras	O usuário entende o que é isso e o que acontece a seguir?	references/microcopy-and-labels.md
2	Estrutura	Quais ações existem, como são agrupadas e ordenadas?	references/inline-keyboards.md, references/reply-keyboards.md
3	Navegação	Como chego aqui, volto e saio? Em qual estado estou?	references/navigation-and-flows.md
4	Renderização do corpo	O conteúdo é legível — tabela, lista, cabeçalhos, texto simples?	references/format-selection.md, references/tables.md
5	Ênfase	Qual é a ação aqui? O que é perigoso?	references/buttons-and-styles.md, references/custom-emoji.md

Uma tela que falha na camada 1 não pode ser salva pelas camadas 4–5. Nunca comece pela cor.

Essenciais dos botões (regras completas em references/buttons-and-styles.md)

Exatamente uma ação por botão inline. De acordo com a Bot API, InlineKeyboardButton requer exatamente um dos campos diferentes de text, icon_custom_emoji_id e style (url, callback_data, web_app, login_url, switch_inline_query*, copy_text, callback_game, pay). KeyboardButton permite no máximo um de seus campos não-text/icon/style.

style (Bot API 9.4) — opcional, exatamente um de:

style	Cor	Significado	Rótulos típicos
primary	azul	A ação principal da tela	Continuar, Iniciar, Abrir, Próximo, Escolher
success	verde	Confirmar / completar positivamente	Salvar, Confirmar, Publicar, Enviar, Finalizar
danger	vermelho	Ação destrutiva ou irreversível	Excluir, Redefinir, Cancelar inscrição, Sair, Cancelar plano
omitido	padrão do app	Todo o resto	Voltar, Configurações, Ajuda, opções secundárias

Se style for omitido, um estilo específico do app é usado. No máximo um primary por tela. danger apenas para ações genuinamente destrutivas, emparelhado com uma etapa de confirmação. Ações secundárias como "Voltar" normalmente permanecem sem estilo.

icon_custom_emoji_id (Bot API 9.4) — mostra um emoji personalizado antes do texto do botão. Utilizável apenas por bots que compraram nomes de usuário adicionais no Fragment, ou em mensagens enviadas diretamente pelo bot para chats privados, grupos e supergrupos quando o proprietário do bot tem Telegram Premium. Nunca invente um ID — obtenha-o (references/custom-emoji.md) ou peça ao usuário.

Ambos os campos são decoração sobre um botão funcional: o rótulo deve ainda fazer sentido sem cor e sem ícone.

Corpo da mensagem: o ajuste mais rico que ajuda

Necessidade	Use
Linhas/colunas ou dados rótulo→valor	Tabela — references/tables.md
Documento estruturado: relatório, resposta de IA, comparação, checklist	Markdown Rico
Conteúdo com template no servidor, controle preciso de tags	HTML Rico
Geração tipada a partir de dados / CMS / AST	Blocos InputRichBlock
Tela com teclado: prompt curto + opções	HTML comum, curto
Controle exato de deslocamento, sem parse_mode	MessageEntity
Nenhum estilo necessário	Texto simples

Regra: dados estruturados viram uma tabela real, nunca uma grade monoespaçada — mas uma tela de menu é um prompt curto mais botões, não um ensaio. Matriz completa: references/format-selection.md.

Feedback enquanto o bot está processando

Esperar sem sinal é a falha de UX mais comum em bots. Escolha com base na forma da operação (regras completas: references/dynamic-feedback-and-streaming.md):

Situação	Mecanismo
Botão inline tocado	answerCallbackQuery primeiro, depois faça o trabalho
Operação de 2–5 s	sendChatAction (typing, upload_photo, …) — máximo de 5 s
Texto de IA sendo gerado (chat privado)	sendMessageDraft — mesmo draft_id, finalize com sendMessage
Resposta de IA com estrutura	sendRichMessageDraft + <tg-thinking> → sendRichMessage
Estágios reais e nomeáveis	editMessageText, limitado
Progresso não mensurável	Estágios nomeados — nunca uma porcentagem falsa
Processo interativo	Mini App (BottomButton.showProgress(), WebApp.ready())

Nunca edite por token: atualize a cada ~800–1500 ms, ~30–80 novos caracteres, uma frase concluída ou uma mudança real de estágio — e respeite retry_after. Um draft_id / message_id / operation_id por operação, finalizado exatamente uma vez.

Qual referência ler (roteada por tarefa — não leia todas)

UI / UX

• Rótulos de botões, redação de mensagens, tom, emoji em texto → references/microcopy-and-labels.md
• Cores style, ênfase, layout e agrupamento de botões → references/buttons-and-styles.md
• Teclados inline, callback_data, paginação, edição no lugar → references/inline-keyboards.md
• Teclados de resposta, ForceReply, remoção de teclado, placeholders → references/reply-keyboards.md
• Telas, estados, voltar/início, comandos, botão de menu, deep links → references/navigation-and-flows.md
• Emoji personalizado em botões e texto, obtenção de IDs, elegibilidade → references/custom-emoji.md
• Respostas em streaming, blocos de pensamento, barras de progresso, carregadores, ações de chat → references/dynamic-feedback-and-streaming.md
• Personalização com dados do usuário, links, previews, deep links → references/personalization-and-links.md
• Consistência entre telas + checklist pré-finalização → references/consistency-and-review.md
• Histórico da Bot API relevante para UI e portões de versão → references/ui-changelog.md
• Cenários antes/depois trabalhados → references/examples-before-after.md

Renderização de conteúdo

• Tabelas → references/tables.md
• Mensagens Ricas / blocos / matriz de capacidades → references/telegram-capabilities.md
• HTML / MarkdownV2 / entidades / legendas / previews → references/regular-formatting.md
• Escolha de formato → references/format-selection.md
• Mídia → references/rich-media.md
• Limites e divisão → references/limits-and-splitting.md
• Rascunhos em streaming e edição → references/streaming-and-editing.md
• Canais, notificações, transmissões → references/channels-and-broadcasting.md

Engenharia

• Investigação de um projeto desconhecido → references/project-adaptation.md
• Escape / injeção / conteúdo do usuário ou IA → references/security-and-escaping.md
• Localização, RTL, comprimento do rótulo do botão → references/localization-and-rtl.md
• Erros, fallbacks, clientes antigos → references/errors-and-fallbacks.md
• Lacunas do SDK / payloads brutos da Bot API → references/sdk-compatibility.md
• Testes → references/testing-playbook.md
• Fontes e datas da última verificação → references/official-sources.md

Validadores locais: scripts/validate_skill.py, scripts/validate_references.py, scripts/validate_keyboard.py (regras JSON do teclado — offline, sem token). Cenários de gatilho: evals/activation-evals.md.

Regras inegociáveis

• Preserve o comportamento. Mantenha callback_data, URLs, deep links, payloads e roteamento de handlers existentes. Um redesign visual não deve reescrever handlers. Se uma mudança em callback_data for inevitável, diga e atualize cada handler/rota na mesma alteração.
• Palavras antes de pixels. Corrija o rótulo antes de adicionar uma cor ou um emoji.
• Sem cor decorativa. Atribua style de acordo com o significado da ação. Não colore todos os botões; um teclado todo colorido não tem hierarquia.
• styl ... [O conteúdo foi truncado, mas a tradução mantém o formato original]