coastdigitalgroup/coastai-skills

Sistema de Comentários e Discussão

Propósito

O Sistema de Comentários e Discussão fornece uma metodologia para projetar camadas de conversação interativas. Ele garante que diálogos complexos e multi-usuário permaneçam legíveis, navegáveis e organizados. Ao definir regras para encadeamento, limites de aninhamento, prioridade de ação e sinalização de contribuidores, este sistema evita "espaguete de informação" e ajuda os usuários a encontrar as contribuições mais valiosas em ambientes de alto volume.

Casos de Uso

• Fóruns Comunitários: Projetar discussões encadeadas para comunidades de nicho.
• Comentários em Artigos/Blogs: Permitir feedback do leitor em conteúdo de formato longo.
• Colaboração SaaS: Estruturar discussões internas dentro de tarefas de projeto, documentos ou pull requests.
• Suporte Q&A: Organizar perguntas de clientes e respostas da equipe.
• Feeds Sociais: Gerenciar interações em postagens ou mídias compartilhadas.

Quando NÃO Usar

• Mensagens Diretas (Chat): Para mensagens em tempo real 1 para 1 ou em pequenos grupos, use um layout otimizado para "balões de mensagem" e entrega instantânea.
• Feeds de Anúncios Apenas: Onde os usuários não podem responder ou interagir; uma lista simples de notificações é suficiente.
• Páginas de Baixa Interação: Se uma página espera menos de 3 comentários no total, uma lista plana sem encadeamento é mais eficiente.
• Logs Transacionais: Para logs de auditoria automatizados do sistema, use timeline-activity-system.

Entradas

1. Modelo de Hierarquia: Quão profundas as linhas de discussão podem ir? (Plano, aninhado ou híbrido).
2. Dados de Identidade do Usuário: Avatares, nomes de exibição e papéis (por exemplo, Moderador, Autor, Equipe).
3. Métricas de Engajamento: Contagens de votos (A favor/Contra), contagens de respostas e timestamps.
4. Metadados Contextuais: Selos de "Compra Verificada", "Principal Contribuidor" ou "Autor".

Saídas

1. Especificação da Anatomia do Comentário: Definição visual de um único "Nó" de comentário (Avatar, Metadados, Corpo, Ações).
2. Blueprint de Encadeamento: Regras espaciais para aninhamento, incluindo incrementos de indentação e "Linhas de Encadeamento" verticais.
3. Mapa de Hierarquia de Ações: Classificação de prioridade para "Responder", "Votar", "Editar" e "Denunciar".
4. Estratégia de Adaptação Responsiva: Regras para recolher encadeamentos ou achatar layouts em dispositivos móveis.

Fluxo de Trabalho

1. Definir a Anatomia do Comentário

Estabelecer uma estrutura de "Nó" consistente:

• O Cabeçalho: Avatar do usuário (dimensionado pelo nível de aninhamento), nome de exibição, selos de papel e timestamp relativo (por exemplo, "há 2h").
• O Corpo: O conteúdo de texto, suportando markdown ou rich text quando apropriado.
• A Barra de Ações: Ações primárias (Responder, Votar) e secundárias (Compartilhar, Denunciar, Editar).

2. Estabelecer Regras de Encadeamento e Aninhamento

Gerenciar a relação espacial entre respostas:

• Indentação: Use um incremento consistente (por exemplo, 24px ou 1.5rem) para respostas aninhadas.
• Linhas de Encadeamento: Use linhas verticais sutis (largura de 1px) para conectar visualmente uma resposta ao seu pai.
• Limite de Aninhamento: Defina uma profundidade máxima (geralmente 3–5 níveis) antes de achatar o encadeamento ou exigir um link "Continue este encadeamento" para uma nova visualização.

3. Classificar Prioridade de Ação

Nem todas as ações são iguais; use peso visual para guiar o usuário:

• Primárias: "Responder" e "Votar" devem estar imediatamente visíveis.
• Secundárias: "Compartilhar" ou "Link" podem ser apenas texto ou apenas ícone.
• Excedente: Coloque "Editar", "Excluir" e "Denunciar" dentro de um menu "Mais" (reticências) para reduzir a desordem.

4. Implementar Sinalização e Confiança

Use dicas visuais para fornecer contexto:

• Destaque do Autor/Equipe: Use uma cor de fundo distinta ou um selo proeminente para o autor original ou equipe oficial.
• Comentários Novos/Destacados: Use um desbotamento sutil de fundo ou acento na borda esquerda para sinalizar comentários não lidos ou recém-publicados.
• Visualização de Votos: Use cor (por exemplo, Laranja para votos a favor, Azul para votos contra) apenas quando ativo.

5. Planejar Adaptações Responsivas

Encadeamentos consomem espaço horizontal rapidamente; adapte para viewports estreitas:

• Achatamento Móvel: Reduza incrementos de indentação em dispositivos móveis (por exemplo, de 24px para 8px) ou limite o aninhamento a 2 níveis antes de achatar.
• O "Pivô de Tela Cheia": Para encadeamentos profundos, permita tocar em uma resposta para abri-la e seus filhos em um "modo de foco" dedicado e de largura total.

Regras de Decisão

• Indentação vs. Plano: Use indentação para "Descoberta" (onde o contexto do pai é crítico). Use listas planas com referências "@menção" para ambientes de "Tarefa" (onde a informação mais recente tem prioridade).
• Exibição de Votos: Mostre votos contra apenas se a comunidade exigir "Autopoliciamento". Para a maioria dos ambientes de crescimento positivo, mostre apenas votos a favor.
• Ordenação Padrão: Padrão para "Melhores" (pontuação ponderada) para comunidades, mas "Mais Recentes" para ferramentas de colaboração sensíveis ao tempo.
• Regra de Truncamento: Trunque comentários extremamente longos (>500 palavras) com um botão "Leia Mais" para preservar o ritmo vertical do encadeamento.

Restrições

• Acessibilidade: Os comentários devem ser navegáveis pelo teclado (Tab pelas ações). Use HTML semântico (<article> para comentários, <ul>/<li> para aninhamento). Toda ação deve ter um rótulo claro. "Linhas de encadeamento" devem ser puramente decorativas (ocultas do ARIA) ou usar aria-hidden="true".
• Responsividade: A indentação não deve empurrar o conteúdo para fora da borda da tela. Use padding-left ou margin-left em contêineres, nunca larguras fixas para blocos aninhados.
• Desempenho: Para encadeamentos de alto volume (>100 comentários), use "Carregamento Preguiçoso" ou paginação "Carregar Mais" para evitar longos tempos de renderização inicial.

Padrões Comuns de Falha

• Morte por Indentação: Permitir aninhamento infinito até que o texto tenha 1 caractere de largura no lado direito da tela.
• Sobrecarga de Ações: Mostrar 10+ botões sob cada comentário, criando um "mar de ícones".
• Hierarquia Invisível: Não conseguir distinguir entre o "Autor" e um comentarista comum, tornando difícil encontrar respostas oficiais.
• O "Pai Perdido": Encadeamentos profundos sem linhas de encadeamento, dificultando rastrear qual resposta pertence a qual pai.
• Estado Ausente: Não mostrar um estado "Pendente" ou "Enviando" quando um usuário submete um comentário.

Critérios de Validação

• A profundidade de aninhamento é limitada e faz a transição para uma visualização plana ou de "foco".
• A hierarquia visual distingue entre Autor, Equipe e usuários comuns.
• Linhas de encadeamento conectam claramente as respostas aos seus comentários pai.
• Ações primárias (Responder/Votar) são visualmente proeminentes em relação às secundárias.
• A indentação se adapta para viewports móveis para evitar estouro horizontal.
• Os comentários são marcados semanticamente como uma lista aninhada ou artigos.
• Os botões de ação têm um alvo de toque mínimo de 44x44px.