Como a note inc. aumentou a adesão às diretrizes da Web moderna de 61% para 94% usando o Modern Web Guidance

Syna Kim
Syna Kim
Takehiko Itabashi
Takehiko Itabashi VP of Technology, note inc.

Publicado em: 10 de novembro de 2026

Contexto: modernização da arquitetura de front-end com padrões da Web

A note inc. é uma das maiores plataformas de criadores de conteúdo e mídia do Japão, atendendo a mais de 90 milhões de usuários ativos por mês. Como parte de um esforço contínuo para modernizar o front-end, os aplicativos da Web do note são criados com Next.js e React.

A equipe de engenharia de front-end incorporou assistentes de programação com IA ao fluxo de trabalho de desenvolvimento. Para ajudar essas ferramentas a gerar código moderno e compatível com padrões, o Google lançou o Modern Web Guidance, um conjunto de habilidades que integra conhecimento sobre plataformas da Web, práticas recomendadas e dados de compatibilidade de navegadores diretamente aos seus agentes de programação.

Para avaliar como o Modern Web Guidance afeta o código gerado na base de código do Next.js e determinar como integrá-lo à biblioteca de componentes interna (note-ui), a note realizou uma avaliação comparativa estruturada em seis cenários de interface reais.

O desafio: coordenar componentes internos com padrões da Web

observação mantém o note-ui, uma biblioteca interna de componentes do React que fornece elementos acessíveis e consistentes com a marca, como caixas de diálogo, dicas, acordeões e campos de formulário. As diretrizes da equipe especificam o uso de note-ui para manter a consistência visual e os valores de referência de acessibilidade em toda a plataforma.

A equipe de front-end do note queria determinar onde o Modern Web Guidance oferece o maior benefício arquitetônico e como coordenar melhor os padrões da Web com a biblioteca de componentes atual.

A configuração da avaliação

A note realizou um estudo comparativo em clones da base de código de produção do Next.js em seis tarefas de interface reais, comparando três condições:

  1. Sem orientação: ferramentas de IA que operam sem o Modern Web Guidance.
  2. Com orientação explícita: ferramentas de IA equipadas com o Modern Web Guidance e solicitadas a consultá-lo.
  3. Com orientação implícita: Modern Web Guidance disponível no repositório sem menção explícita ao comando.

As seis tarefas foram categorizadas com base na relação delas com a biblioteca de componentes internos do Notes:

  • Tarefas cobertas por note-ui: caixa de diálogo de confirmação da exclusão.
  • Tarefas fora do escopo do note-ui: cabeçalho que diminui ao rolar a página, otimizações de velocidade da página do artigo.
  • Tarefas parcialmente cobertas por note-ui: acordeão de perguntas frequentes (exigindo comportamento de abertura única e capacidade de localização na pesquisa na página), dicas de ferramentas de perfil de usuário avançadas, formulários de inscrição de membros.

As implementações foram verificadas não apenas por análise de código estático, mas também pela inspeção de propriedades DOM e CSS renderizadas em testes automatizados de navegadores Chromium e WebKit.

Veja a seguir os seis cenários de interface e a nota de critérios funcionais avaliada.

Caixa de diálogo de confirmação de exclusão
Abre ao clicar em Excluir. Fecha com Esc, clique no plano de fundo ou botão "Cancelar"
Cabeçalho que diminui ao rolar
A altura inicial é 120px, diminui para 64px ao rolar e permanece fixo na parte de cima
Dica avançada para o usuário
Aparece ao passar o cursor e com o foco do teclado; desaparece quando o ponteiro sai
Perguntas frequentes em acordeão
Abre ao clicar. Quando um item é aberto, os anteriores são fechados automaticamente.
Formulário de inscrição de membro
Suprime erros durante a digitação ativa; exibe erros de validação no desfoque do campo
Renderização da página do artigo
A maior imagem na janela de visualização tem alta prioridade e não é carregada de forma lenta. Os cards fora da tela usam content-visibility: auto;, e as imagens fora da tela são carregadas de forma lenta.

Principais descobertas: onde as diretrizes para a Web moderna têm o maior impacto

Para medir o impacto real do Modern Web Guidance, a note executou uma avaliação estruturada em 180 execuções em clones do repositório de produção do Next.js. Eles avaliaram dois agentes de programação de fronteira comercial em seis cenários de interface em três condições: sem orientação, com orientação não solicitada (habilidade no nível do repositório disponível) e com comandos explícitos.

Os pacotes de testes automatizados verificaram o DOM renderizado, o layout e as propriedades CSS computadas em ambientes de execução de navegador Chromium e WebKit headless em relação a 19 critérios definidos nos padrões modernos da Web.

Aderência aos padrões da Web por condição de avaliação

Agente de programação Valor de referência Orientação espontânea Orientação explícita Aumento líquido
Agente A
Modelo principal
60,8%
sem orientação
76,5%
+15,7 p.p.
94,0%
de desempenho máximo
+33,2 pt
p < 0,001
Agente B
Modelo secundário
75,8%
sem orientação
86,2%
+10,3 p.p.
90,0%
alta precisão
+14,2 p.p.
p < 0,001
Sobre a metodologia: a porcentagem representa a adesão da plataforma em 19 verificações automatizadas de navegadores no Chromium e no WebKit. Os testes confirmaram que o código gerado adotou recursos nativos da Web em vez de JavaScript personalizado legado.

1. Melhorias de arquitetura e desempenho

O Modern Web Guidance provou ser um complemento poderoso para a arquitetura atual do Note. Enquanto a biblioteca de componentes note-ui manteve a consistência da marca para elementos da interface padrão, o Modern Web Guidance equipou as ferramentas de IA para lidar com comportamentos interativos complexos e otimizações de desempenho usando APIs nativas do navegador.

Sem orientação, as ferramentas de IA costumavam gerar listeners de eventos JavaScript personalizados, gerenciamento de estado manual e carregamento de recursos ad hoc. Com as orientações da Web moderna, as ferramentas adotaram de forma consistente recursos nativos declarativos e reforçaram as práticas recomendadas de desempenho crítico.

Impacto da adoção de padrões modernos da Web em comparação com a implementação sem orientação

Recurso e API nativa Sem orientação Com o Modern Web Guidance
Cabeçalho que diminui ao rolar
animation-timeline: scroll()
❌ Listener JS imperativo
É executado na linha de execução principal e causa instabilidade na rolagem
✅ Compositor fora da linha de execução principal
Animação de rolagem CSS declarativa; código de listener JS zero
Dica interativa
API Popover
❌ Matemática de coordenadas JS personalizada
Cálculos manuais de janela de visualização e redimensionamento frágeis
✅ 0 KB de sobrecarga de pacote
Posicionamento nativo na camada superior; zero matemática personalizada ou wrappers de DOM
Perguntas frequentes pesquisáveis
<details name="faq">
❌ Estado de alternância personalizado do React
Conteúdo oculto da pesquisa de texto na página (Ctrl+F), ARIA manual
✅ Pesquisa nativa in-page
O navegador se expande automaticamente ao pressionar Ctrl+F; código de sincronização de estado zero
Imagem principal candidata à LCP
fetchpriority="high"
❌ Antipadrões conflitantes
Alta prioridade combinada com carregamento lento em imagens principais
✅ Descoberta antecipada de análise de HTML
Desacoplada do carregamento lento; +28% de adoção em PRs pós-MWG
Formulário de inscrição acessível
autocomplete e HTML semântico
❌ Tokens de preenchimento automático ausentes
Avisos de erro acessíveis omitidos
✅ Preenchimento automático do navegador sem complicações
Entradas nativas e anúncios ARIA; +69% de adoção do preenchimento automático
Observação sobre a metodologia: as linhas de 1 a 3 refletem os resultados de arquitetura verificados em 180 execuções de teste de navegador headless. As linhas 4 e 5 incluem os ganhos de adoção de produção medidos em 431 PRs pós-introdução.

Os impactos do Modern Web Guidance na sua base de código variam de acordo com os comandos e os recursos usados. Para um exemplo concreto, veja como os listeners de rolagem imperativos do JavaScript para o cabeçalho foram substituídos por animações de rolagem nativas do CSS.

/* With Modern Web Guidance: CSS scroll-driven animation (excerpt, CSS Modules) */
.header {
  --shrink-progress: 0;
  --shrink-distance: calc(var(--header-max-height) - var(--header-min-height));

  position: fixed;
  inset: 0 0 auto;
  /* Without support, a JS fallback updates --shrink-progress */
  height: calc(var(--header-max-height) - var(--shrink-distance) * var(--shrink-progress));
}

/* The shadow fades in through opacity only */
.header::after {
  content: "";
  position: absolute;
  inset: 0;
  pointer-events: none;
  box-shadow: var(--elevation-4);
  opacity: var(--shrink-progress);
}

@supports ((animation-timeline: scroll()) and (animation-range: 0% 100%)) {
  .header,
  .header::after,
  .logo {
    animation-duration: auto;
    animation-timing-function: linear;
    animation-fill-mode: both;
    animation-timeline: scroll(block root);
    animation-range: 0px var(--shrink-distance);
  }

  .header { animation-name: header-shrink; }
  .header::after { animation-name: header-shadow; }
  .logo { animation-name: logo-shrink; }
}

@media (prefers-reduced-motion: reduce) {
  .header,
  .header::after,
  .logo {
    animation-timing-function: steps(1, end);
  }
}

@keyframes header-shrink { to { height: var(--header-min-height); } }
@keyframes header-shadow { to { opacity: 1; } }
@keyframes logo-shrink   { to { transform: scale(0.5); } }

2. Estabelecer o limite operacional certo para sistemas de design internos

A avaliação também destacou como as ferramentas de programação de IA interpretam as instruções. Quando as ferramentas receberam uma instrução explícita e incondicional para seguir as orientações da Web, elas selecionaram naturalmente elementos HTML nativos (como <dialog> ou <input> nativos), mesmo quando um componente note-ui preexistente estava disponível.

observou que a solução é simples: em vez de tratar as orientações da Web como uma alternância de tudo ou nada, as equipes alcançam o melhor resultado estabelecendo uma hierarquia de regras clara nas instruções do repositório (como AGENTS.md).

A decisão: uma estrutura de regras hierárquica no AGENTS.md

Com base nas descobertas da avaliação, o Note estabeleceu uma regra sistemática nas diretrizes do repositório (AGENTS.md) para orientar os desenvolvedores e as ferramentas de IA:

## UI Components and Modern Web Guidance

When building UI, follow this order of precedence. This applies even though the `modern-web-guidance` skill describes itself as mandatory for all HTML/CSS and client-side JavaScript tasks.

1. **Prioritize noteui**: For UI elements already provided by noteui (dialogs, toasts, buttons, form fields, popovers, etc.), use those components and follow existing conventions (such as `useDialogState` and react-hook-form). In apps, import them through `@/ui/noteui`. Do not replace an available component with a native HTML element (such as `<dialog>` or a plain `<input>`) simply because Modern Web Guidance recommends it.
2. **Use Modern Web Guidance where noteui falls short**: For capabilities that noteui does not cover or requirements it cannot meet, consult the `modern-web-guidance` skill before writing HTML, CSS, or client-side JavaScript. For example:
   - Scroll-linked effects: Use CSS scroll-driven animations instead of scroll event listeners.
   - Exclusive or page-searchable disclosure: Use `<details name="...">` and `hidden="until-found"`.
   - Core Web Vitals: Use `fetchpriority` for LCP images and `content-visibility` for off-screen content.
   - Form attributes: Pass attributes such as `autocomplete` and input `type` through the field component's props.
3. **Prioritize existing components when guidance conflicts**: Apply Modern Web Guidance only through the props and attributes supported by the component. For noteui form fields, display validation errors using the component's built-in mechanisms (`validationState` / `errorMessage`, or `HelpText` with `aria-describedby`) rather than custom alert elements.

Ao definir essa hierarquia:

  • A consistência da interface atual é preservada: as caixas de diálogo e os formulários padrão continuam usando note-ui.
  • O JavaScript personalizado é eliminado: novos comportamentos e animações interativos aproveitam os recursos nativos do navegador.
  • A qualidade do código é padronizada: as ferramentas para desenvolvedores seguem automaticamente os padrões modernos da Web onde eles são mais importantes.

Pontos importantes para as equipes de engenharia

  • Use recursos de plataformas modernas onde os sistemas de design terminam: as bibliotecas de componentes são excelentes para elementos de interface de marca, mas os navegadores mais recentes oferecem recursos nativos poderosos para rolagem, pop-overs e prioridades de carregamento. O Modern Web Guidance ajuda as ferramentas para desenvolvedores a adotar esses recursos nativos em vez de escrever JavaScript personalizado.
  • Defina uma hierarquia de prioridade clara: em bases de código com uma biblioteca de componentes existente, adicionar uma ordem de prioridade concisa nos arquivos do repositório (como AGENTS.md) garante que as ferramentas respeitem seu sistema de design ao adotar padrões da Web modernos.
  • Verificar em ambientes de execução de navegadores reais: testar a saída renderizada em navegadores automatizados fornece feedback imediato sobre como o CSS e o HTML modernos interagem com bundlers e ambientes de framework específicos.

"Nossa missão no note é 'Começar e continuar criando'. Por isso, nossa plataforma precisa ser rápida e acessível para todos os criadores e leitores. À medida que mais códigos são escritos com agentes de programação de IA, o Modern Web Guidance ajuda a alcançar soluções modernas e baseadas em padrões, em vez de recorrer a padrões JavaScript mais antigos. Ele também destaca detalhes que podem passar despercebidos, como a prioridade de carregamento de imagens e a acessibilidade de formulários. Combinado com nosso sistema de design, ele nos permite continuar melhorando o Note e, ao mesmo tempo, manter nossa interface consistente."

— Takehiko Itabashi, vice-presidente de tecnologia, note inc.