Mentalizei: construindo uma PoC com especificação e clareza técnica
Como uma PoC local-first pode evoluir com JSON estruturado, editor em blocos, grafo de conhecimento e decisões técnicas orientadas por especificação.
O Mentalizei é uma PoC para organizar ideias, notas e relações entre conteúdos. Mais do que testar uma interface de anotações, o projeto funciona como um laboratório para validar decisões de produto, arquitetura e experiência de uso.
A proposta central é simples: antes de sair codando telas, definir bem a estrutura dos dados, o comportamento dos componentes e as regras de interação.
Esse é o ponto do Spec-Driven Development. A especificação não entra como documentação decorativa. Ela serve como referência para orientar o JSON, os componentes e a evolução do produto.
Projeto em funcionamento
O Mentalizei está publicado e disponível para explorar agora:
Acessar o MentalizeiA ideia principal
Quando a estrutura do conteúdo é clara, o código deixa de tentar adivinhar o produto. Parece óbvio, mas boa parte dos bugs nasce justamente quando essa conversa foi pulada.
1. Editor em blocos com menos fricção
O painel de cadastro de conteúdo foi pensado como um editor em blocos estruturados.
A ideia não é criar mais uma tela cheia de campos, mas permitir que o usuário comece a escrever rapidamente, com regras previsíveis e uma estrutura flexível o suficiente para evoluir.
Na criação de uma nova nota, a área de conteúdo já nasce aberta, pronta para digitação, com o cursor posicionado no primeiro bloco.
Regras de UX para o estado inicial
- Ao criar uma nota, o conteúdo deve abrir automaticamente em modo de edição.
- Toda nota nova deve iniciar com dois blocos richText abertos.
- O foco deve ser posicionado no primeiro bloco.
- O usuário deve começar a escrever sem precisar entender a estrutura interna do sistema.
2. Anatomia visual dos blocos
Cada bloco do editor foi separado em duas áreas funcionais.
À esquerda, ficam as ações, como troca do tipo de conteúdo e reordenação.
À direita, fica a área principal de edição, com placeholders contextuais conforme o tipo de bloco.
Mapeamento semântico de conteúdo
| Tipo de conteúdo | Representação JSON | Placeholder sugerido |
|---|---|---|
| Texto | type: "richText" | Escreva um texto... |
| Título H1 | type: "heading", level: 1 | Título principal |
| Título H2 | type: "heading", level: 2 | Subtítulo |
| Título H3 | type: "heading", level: 3 | Seção |
| Relacionamento com @ | type: "richText" com mention token | Digite @ para relacionar... |
| Tabela | type: "table" | Adicionar tabela |
Decisão técnica da V1
Na primeira versão, o relacionamento com @ permanece como richText contendo um token de menção. Isso evita criar tipos demais cedo demais. Todo schema que cresce antes da hora cobra juros depois, e geralmente com multa.
3. Escrita contínua sem interromper o fluxo
A experiência do editor precisa respeitar o fluxo de pensamento.
Por isso, o Mentalizei utiliza uma barra de adicionar ao final da lista e também permite criar um novo bloco richText ao pressionar Enter no último bloco.
O objetivo é simples: reduzir cliques, manter o contexto e evitar que o usuário precise alternar mentalmente entre escrever e configurar a ferramenta.
4. Evolução do token @hoje
A evolução da palavra reservada @agora para @hoje mostra uma decisão importante: evoluir sem quebrar o que já existe.
Ao digitar @hoje, o sistema substitui o gatilho por um dateToken.
A data exibida segue o formato em português brasileiro, como "4 de maio de 2025", sem zero à esquerda e com o mês por extenso.
Comportamentos do @hoje
- O token deve ser renderizado como componente clicável.
- Ao clicar, deve abrir um calendário em tooltip para ajuste manual.
- O parser deve continuar aceitando @agora como legado.
- Durante a edição, @agora deve ser convertido internamente para o novo formato canônico.
5. Grafo de conhecimento como navegação
O grafo do Mentalizei não deve existir apenas para parecer sofisticado.
Ele precisa ajudar o usuário a identificar relações, agrupamentos e caminhos entre notas.
Para melhorar a legibilidade, os títulos aparecem abaixo dos nós, evitando excesso de informação dentro do próprio grafo.
Modo de foco
Ao passar o mouse sobre um nó, o sistema destaca suas conexões diretas e reduz a opacidade dos demais elementos. Isso limpa o ruído visual e ajuda o usuário a analisar uma relação por vez.
Explore o grafo na prática
O grafo de conhecimento, o editor em blocos e todas as decisões técnicas descritas aqui estão funcionando no projeto.
Paleta de categorias
| Categoria visual | Cor | Hexadecimal |
|---|---|---|
| Azul acinzentado | Fria | #7C9AB8 |
| Verde sálvia | Fria | #8FAF9A |
| Areia quente | Quente / contexto | #C9B38C |
| Terracota clara | Quente / contexto | #C98F7C |
| Rosa empoeirado | Quente / contexto | #C79AA5 |
| Mostarda suave | Quente / contexto | #C7B06D |
| Lavanda suave | Destaque | #A999C8 |
| Cinza ardósia suave | Neutra | #8B96A3 |
Fallback técnico
Categorias legadas sem cor definida devem assumir o cinza neutro #B8BEC6. Não é glamouroso, mas fallback bom é aquele que evita surpresa ruim em produção.
6. Separação entre workspace e editor
Uma decisão importante da arquitetura foi separar o contexto gerencial do contexto de edição.
A Home não precisa tentar resolver tudo ao mesmo tempo. Quando uma tela tenta ser painel, editor, busca, grafo e dashboard, normalmente ela faz tudo de forma mediana.
A separação de rotas ajuda a organizar responsabilidades e permite otimizações específicas para cada caso de uso.
Organização das rotas
| Contexto | Rota | Responsabilidade |
|---|---|---|
| Workspace | / | Exploração, busca macro, notas recentes, categorias e grafo de conhecimento. |
| Editor | /notes/[slug] | Edição de uma nota existente. |
| Nova nota | /notes/new | Criação de uma nova nota com estado inicial padronizado. |
7. PWA e abordagem local-first
O Mentalizei foi pensado para funcionar bem como aplicação local-first.
A instalação como PWA permite que a experiência básica não dependa o tempo todo de comunicação com backend.
Para um bloco de notas inteligente, isso faz sentido: escrever precisa ser rápido, disponível e pouco dependente de infraestrutura externa.
Decisões técnicas do PWA
- Manifest configurado com display: standalone.
- Suporte a viewportFit: cover para respeitar safe areas em dispositivos iOS.
- Service Worker com estratégia network-first e fallback para cache.
- Verificação de atualização em intervalo de 1 hora para evitar versões antigas por muito tempo.
Conclusão: especificação também é engenharia
A PoC do Mentalizei mostra que a complexidade de um produto não está apenas no framework escolhido.
Boa parte da complexidade está na estrutura do dado, na semântica do JSON, na separação das responsabilidades e na fricção da experiência.
Código importa, claro. Mas código sem especificação vira tentativa organizada. Às vezes nem tão organizada assim.
A pergunta final é simples: seu projeto tem uma especificação clara ou apenas uma coleção crescente de decisões implícitas?
Veja o resultado final
Tudo que foi discutido nesse post está implementado e publicado:
Acessar o MentalizeiQuer discutir produto, engenharia e especificação?
Esse tipo de conversa costuma evitar algumas semanas de retrabalho. Não todas, porque ainda vivemos no mundo real.