MasterStyles: Documentos que finalmente têm a aparência correta

Seus documentos acabaram de receber uma atualização visual. Blocos de código são renderizados com destaque de sintaxe, diagramas Mermaid são legíveis por todos e imagens de destaque mudam com base no seu conteúdo.

O que estava errado

O MasterStyles tinha uma lacuna de renderização. Blocos de código delimitados em HTML, JavaScript ou Python eram renderizados como texto simples -- sem destaque de sintaxe ou estrutura visual. Os diagramas Mermaid usavam temas de cores que falhavam nos padrões de acessibilidade. Os documentos piscavam durante o carregamento. As imagens de destaque eram espaços reservados estáticos, independentemente do conteúdo.

Esses problemas se acumulavam. Um documento bem estruturado parecia amador quando renderizado.

O que mudou

Blocos de código com destaque de sintaxe

Blocos de código delimitados agora são renderizados com o devido destaque de sintaxe em HTML, JavaScript e Python. A função de borda convert-md-to-html lida com a detecção de linguagem e aplica destaque compatível com o tema antes que o conteúdo chegue ao seu navegador.

Nenhuma configuração necessária. Escreva seus blocos de código como de costume -- o pipeline de renderização cuida do resto.

Diagramas Mermaid acessíveis

Cada diagrama Mermaid -- fluxogramas, diagramas de sequência, ERDs, C4 -- agora é renderizado com temas de cores acessíveis e de alto contraste. Isso se aplica a tipos de variáveis em Markdown e HTML.

Testamos em relação às taxas de contraste WCAG. Elementos escuros em fundos claros, texto de rótulo claro e codificação de cores distinguível. Chega de forçar a vista em rótulos de nós de baixo contraste.

Imagens de destaque dinâmicas

As imagens de destaque agora mudam com base no tema da sua variável. O sistema extrai de um catálogo armazenado em mvpl_parameters, combinando o tópico da variável com imagens relevantes. Um documento de estratégia recebe um destaque diferente de uma especificação técnica.

Chega de oscilação

O componente HtmlSandbox agora faz o debouncing das passagens de contraste durante o carregamento. Anteriormente, o pipeline de renderização piscava entre os estados conforme o CSS era carregado de forma assíncrona. Agora, o CSS é carregado em paralelo por meio do gancho useAllCss() com o cache HTTP habilitado. O resultado: renderização suave desde o primeiro quadro.

Por que isso importa

Os documentos são a principal saída do trabalho assistido por IA no Masterminds. Se a saída renderizada parecer pouco profissional, toda a plataforma parecerá pouco profissional -- independentemente de quão bom seja o conteúdo da IA.

Esta versão fecha essa lacuna:

• Documentos densos em código agora são fáceis de escanear e profissionais
• Documentos densos em diagramas funcionam para todos, incluindo usuários com deficiências visuais
• Primeiras impressões são suaves -- sem artefatos de carregamento ou oscilação

Notas técnicas (para engenheiros de software)

• Pipeline de renderização: A função de borda convert-md-to-html lida com a detecção e o destaque de blocos delimitados
• Fonte da verdade do CSS: src/index.css com 3 variantes (não escopado, escopado em .mm-doc-root, pontos de interrupção responsivos)
• Pipeline de compilação de CSS: scripts/build-mm-html-style.mjs gera 4 arquivos de saída -- NUNCA edite public/mm_html_style*.css diretamente
• Temas Mermaid: Padrões acessíveis aplicados tanto na pré-renderização da função de borda quanto na renderização do navegador
• Catálogo de imagens de destaque: Armazenado em mvpl_parameters via migração 20260211190000_add_masterstyles_hero_images_parameter.sql
• Debounce de contraste: HtmlSandbox.tsx faz o debouncing da passagem de contraste para evitar oscilações durante o carregamento paralelo de CSS

O que vem a seguir

• Temas personalizados por espaço de trabalho (planejado)
• Exportação de PDF com renderização MasterStyles (em design)
• Anotações colaborativas em documentos renderizados (estágio de conceito)